Rust Programming Language Rust Linz, 8 Feb 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Rust Linz, January 2021 - Karl Grasegger - Unleash the power of your comments!

Description

Unleash the Power of your Comments

A quick introduction to *rustdoc*, and how it helps you to make the probably most boring part of programming more pleasant.

Rust Linz:
https://twitter.com/rustlinz
https://rust-linz.at
https://sessionize.com/rust-linz

A

So, okay, now that you said it, I realized that the title of my presentation is a bit um over hyped, but it's a great topic. I think really, so I couldn't help myself. I had to use this really cool animation unleash the power of your comments, um and this really is. uh I want to provide something for everyone, if, even if you're, a beginner or if you're a long-term rest user, I want to show some tricks everyone can use for the projects.

A

So, first of all a quick note, we probably all know that comments are very important, and this is a very bad example of a comment, because comments should add value.

A

I'm saying this because I'm going to ignore it today, because you can't teach comments by writing good comments or yeah. You can, but you can't teach about brass talk by only writing good comments, or I would have not enough time. So why would someone talk about comments at all?

A

I am the first to rant about it. If it's missing um it's so important and in my daily work I have to do with a lot of really old projects. uh Just today I discovered a dependency on a 2012 version of a library, so comments help me a lot and I miss them a lot too in those projects, but at the same time I struggle with them. Good comments are really hard to do and with rust it's always the ecosystem that gets the language even at one level up, so that that's really important for us.

A

I think that you not only look at the language, but what's already there to help, you build your things because in other languages it's commenting was kind of an add-on and, for example, in php you have various commenting system and there's some standard stuff, but uh every team does it a bit different.

A

So it's great to see it's built in and you can rely on it and I love reading a good documentation. I have a tip about one at the end of my talk.

A

Okay, so I have prepared some code well rather documentation. um I've prepared a workspace here and this will be uploaded to github. So you can look at it in your own time if you want to dive deeper into it and, let's just start with a really simple trust, talk comment. My font is so big. I can't fit the lines.

A

You see here we have in the first line. We have two slash pictures, that's a classic comment. That's a comment you can just write anywhere at rusdoc doesn't interact with it at all and if you use three slashes, then you have a rest, a rust dock comment and this is attached to the main function.

A

Now. This is great and all I have my comments here, but what really makes it just that much better is that you get uh rust stock when you install cargo or the rust default setup from bus, stop you get rust dock and I'm using cargo for this demo, but you could just use rust dock, so I'm going to execute cargo dock with the open parameter that builds the documentation and opens it in my default browser.

A

I'm going to start a loop here, so it's just built in the background from now on and all of this I get for free, I don't have to do anything to get this. Besides. Writing this one comment, I get my crates, I get a list of functions.

A

um I get some navigation some pages, I even get a search, and this is a part of what makes rostock so great because you don't have to think about the next step. What libraries do I need to use to get a nice documentation and yeah? So that was one of the points where I was like whoa.

A

This is just great and it also explains why all the documentation of of the online rust stuff is so great because you get so much help building it.

A

Okay. This was just a really quick introduction. Those grades I built here built upon the one that came before so I introduced a change in every one of those steps.

A

The next thing I added was um documentation for a module. I'm writing.

A

In this case. It's named mimod and here's something special because rustoc can make. I can see if you are using the three slashes or the two slashes with the exclamation point, and this is a top level comment and you'll see what I mean when I build it and open it in rust. Dock.

A

Top level comments are well on the top level of something, so you can provide a really quick overview over what's happening in this module in a main view of your crate. So users of your api can quickly um see what's going on in there and jumping really quick, I'm way quicker than I thought into the next one.

A

I added a top level comment to the main.rs, and this is really cool.

A

This is, is a common for my whole crate.

A

So I can write an extensive comment about what this crate tries to accomplish, what um what a user should be very off or something else important and you could you can place it at the top of your documentation and you don't need to clutter up some different files or include something, but you can I'm going to show you how later?

A

Oh, I don't think I do because it was nightly. Well, we see um I will talk about advanced features, okay, so so far so good, we have some great level comments, module level comments, function, level, comments and here's something really clever. I guess you can guess it from the great name.

A

This is all just markdown and I didn't know I wanted this until I used this because sometimes in documentation you need to emphasize and it's easy to emphasize with markdown, and we have some more benefits I will show later so I I think at this point alone: it's amazing what rustoc can do for you. It's really easy. It's really in the programming flow, you don't have to think a lot and you get a really nice documentation out of it.

A

Now, if you are a maintainer of some library or you are a draconian product manager or something I don't know, um you can control a bit what uh what you expect from the rust stock system. So, for example, with this, um it's called lint. I think you can just crash rustoc when there's missing documentation.

A

So everything when you do this, everything in your code needs to be documented.

A

Now in real world situations, you would probably probably just warn about it, so you can just adjust that, like you could just any other warnings.

A

For example, about you can get a warning about function, names that have a big letter at the beginning capital letter and in the same way you can control rustoc yeah. So I'm going to show you how that looks in the browser, because again it's all just markdown, and that means those are nice code blocks which are, I don't know if you can see that stream, but they have a light grey background.

A

So you can write code blocks in here in your documentation, which is great, and that leads perfectly to the next step. We have some code samples we can put into the code and, let's jump into my mod here so.

A

Here you can already see um visual shooter code is uh telling you me to run dock test here. I'm gonna show you what stupid does in a moment.

A

When you put examples into rust stock comments, you can just use the markdown syntax you are familiar with and then you just write rust code, so you can show a user how to use your function right and for short functions. You can just make a document out of it, so I just said: assert equal the value and one two three, by the way, I'm just taking a string into here and making an unsigned intent, unsigned integer here for a nice test, and I don't know if first code can run it. Let's see.

A

No, it does not want to run it. I think I know: what's the problem um doc now wait a second test. Okay, so um I can with a familiar cargo test command which I can use for my other tests. I've set up, I can just add the parameter doc and when I run this uh yeah great, so one downside is it only works with libraries. I think I can.

A

I have to say I want to lab right.

A

Great now that's working out great okay, so you can just run dog tests and I I had this working. I swear.

A

No, that's not going anywhere productive, sorry about that, but they do work for libraries um wait! A second did I no! I didn't include it. Maybe that's the problem, doc. It works right. So that's what's the problem, the workspace wasn't aware of the package and you can see it ran one test in my mod rs and it passed cool and you can for libraries even say that every public api needs to have a doc test, or at least a code example.

A

So that's another great way you can ensure the documentation of your project is up to your standards and this integrates with the whole test. Suites um right. um Let's see I've built this. I didn't. I'm gonna start a loop again. So.

A

I documented a bit about dog tests in, in my documentation of this grade.

A

Dog tests are a bit weird, you can only use it for public methods and, as you have seen only for libraries.

A

um There are some feature: discrepancies with rustoc and cargo dock. You should try out what works better for you. I decided to fall back to cargo dock because it has the lower features and, in my humble opinion, you should not use this test whole modules. You should not use it to have a complex setup, it's great for the things where you have a one line or two liner for some documentation, and you can just make a quick test out of it and to make this even better in your documentation. There's a nice little trick.

A

As you can see here in front of the assignment of input, I've added a hashtag, sorry I I know it's not originally hashtag. I don't remember what it was before, so I added the hashtag here and before I set equal.

A

This may look a bit messy at this point, but if we build this and hop over into the browser- and then I'm going to my mod and I'm, this is a documentation now for this function,.

A

uh That's wrong file great! I'm a bit stressed today, I'm so sorry guys!

A

Okay, here we are so, as you can see, uh rustoc only takes the lines without the hashtags at the beginning into the code examples.

A

So this is really great because you can use a variable to say this should be some input by a user, or you should give me a hash at this point. So you can use a variable name here to say what you expect and your code can still be just drawn as a doc test.

A

But the user here doesn't have to worry about some asset in in their code example this because they don't care about your dog tests at this point right, so I'm going to slow down a bit. Now um I'm going to jump into the last trade here. I have some more content on my slides, um but this was. I really wanted to show this because it's powerful, um we have again.

A

We have marked down and marked down those links, and I, of course can set hyperlinks to anywhere, but rustoc also has a special syntax for internal links. So in this case I should this function should be, should have a lowercase f at the beginning, but I decided I need to have this big f um now.

A

A

Yeah, so here a normal link is just a link and this automatically links to the symbol named links, which is the module links. I should have thought about the naming a bit better, but you can, as you can see here uh up here, if you just write my mod it links to my mod and when we jump back into here, you can see down here that this just works.

A

You don't have to think about if you are linking to a module, a function or anything else, but if you have to think about it, you can you can say this is a struct. This is a function, and uh sometimes it happens that in one creates a name is used twice. So that's a great way to link to the correct item.

A

Cool, so now that I run through all my crates, um I want to showcase the search function again, because it's really great that I get this for free. I I'm amazed.

A

I even get some if you're a dark mode user. You can also do that and yeah. So that was the coding part, and now I'm going to jump back into my slideshow and I have some more topics for you. Can you please start? Thank you. So some goodies I want to talk about are the links I slightly touched on already. External files. Aliasers are really cool and the ras talkbook, so lins, as I said, make sure examples exist or everything is documented.

A

You can check for broken internal links. So if you have a bigger project with a few developers and someone is refactoring something and you link to it, it gets notified you get notified in in the building process because the link is broken and that ensures your documentation is up to date at all places and you can even if you're, if you just want to document the public api, for example, you can check that no public api items are linking to private api items.

A

Then we have aliases.

A

I I'm a really big fan of the search. I don't know if you noticed, um but sometimes it's not uh you. It's not obvious that a a name is not obvious. So, for example, you have a struct foo, but because of historical reasons, everyone just calls it bar, and for that you can just use aliases for your struct. In this example from the rough stock book they used x and big as aliases for big x.

A

So, if you're searching for x, all uh this struct also shows up. This is also great for refactoring. So if you're changing things around, you can set the area old, struct, name or function name as an alias and people can still find what they're looking for next up wait. Did I skip something.

A

Why is my external files? Not here? Well, um then talk about it and then we'll talk about the rest book now the rust.book has some more advanced features documented.

A

It has a detailed talk about all the options you have and some references, and I don't know where the external files slide went, but I can tell you that you can at the moment use excel files even with cargo dock, but you can't use them for the top level comments, so I thought it would be really cool if the big markdown stuff I put on top of my crate was an external file, but that's that's possible at the moment.

A

um They are working on it and that's a really big point, because I have I have a feeling it's a very active um small community around rostock and they have a lot of open issues and they have a lot of things in a pipeline which are really really cool like those external files which are currently a nightly feature.

A

So I would encourage you to just follow the project a bit on the side or just look at it once so. You know you, you know what you can expect because they have some really cool features planned wow. So thanks for listening.

A

um Here's a link for the rust dog book.

A

You can hit me up at carlatinuff.com. If you want to, you, will find a talk and the sources from my other stuff on github.com.

A

I don't have a personal blog at the moment, but if you want to read something by me, I recently blogged about mindfulness on the company blog.

A