rustdoc: beyond documentation
CC Attribution 2.0 Belgium:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Gomez, Guillaume
Rust compiler comes with a few tools, rustdoc is one of them. It is THE standard rust tool to generate documentation for your crates. Rust compiler comes with a few tools, rustdoc is one of them. It is THE standard rust tool to generate documentation for your crates. You can write documentation using "///" or "//!" patterns (which are syntaxic sugar over #[doc = "..."]). It generates HTML which can used locally without a need for internet connection. The documentation search is running in JS directly in your browser. You have a source code viewer integrated. You can pick different themes (and even add one yourself). It works with javascript disabled. It provides settings to make your docs browsing more comfortable. You can generate docs with extra content (take a look at for a good example!). But not only it generates documentation, it also adds things for each type that you didn't know was available thanks to the "Auto-traits implementation" and "Blanket implementation" sections. In addition to generate documentation, it provides functionalities such as an integrated documentation's test runner (which themselves can be quite customized!). It also provides lints that can you deny (missingdocs, missingdoc_example). With just all this, rustdoc is already a quite complete tool. But more will come in the future: more interactive source code viewer automatic link generation based on the item name more output formats supported (json would be the first) cfgs (doctest and doc) doc aliases for search (for instance, "*" proposes pointer in the std lib)
 So as I said, you will have to use a lot of your imagination. And when I say things, just try to have it in your mind or something. So it will be a ResDoc Beyond Democumentation. You can enjoy it. So first, why am I here? So I'm the ResDoc team leader since recently. I'm also part of the documentation team, the docs.res team, and the dev tools team. So you kind of see some kind of pattern, I think, I think, point. So I've started working on ResDoc in 2015, I think. So since then, a lot of things have happened. And my main focus currently is ResDoc and more globally documentation. So I have to work on docs.res and a bit everything, a dot related. So I tried to show how we were able to provide documentation. And most things that we have, which are pretty nice now. So first, what is ResDoc? So ResDoc is a tool provided alongside the compiler and cargo, which is used to generate a documentation, as you may guess. You can do a bit more, but we'll go back to that later on. I think it's kind of most. So that's ResDoc. So raising ResDoc, as you can, you have to mind it. But you can use it multiple ways, like directly through ResDoc and you give it a file and it works. But when you start having dependencies, it's getting a bit tricky. And the command line is getting quite long. So welcome back to make file error. Is it on? It's blinking. Blinking. OK. Yeah, so now you can stop having in your mind. Just read. So like I was saying, you can use it directly through the command line. Or you can use cargo doc, which is making things much simpler. So you don't have to mind about all the dependencies and everything. You just cargo doc and everything is done in the background. And that's pretty nice. And you can even have your web browser open. And going to your page, to your documentation, just add the dash dash open. And that's pretty much it. It's very convenient. So yeah, fun fact. That's something we used for some who don't know it. We have error indexes. And you can, well, we needed to have something to generate a Macdon page. So ResDoc can actually render and convert the Macdon from two HTML. So if at some point you need a convert, it works pretty well. So documenting. We tried to focus on having documentation done as much inside the code as possible. Because in most languages, the documentation and the code is generally split. And you have to rely on tools that are not official. In ResDoc, we had the look that some people came in pretty early, just took the compiler AST and converted it into HTML. So to do so, you can have the documents like that. So slash slash dash, no, not dash. Bang. Bang. Exactly. Exclamation mark is to document the current module. And if you just put slash slash slash, it's to document the following item. So in here, it will be the function. And the previous one will be for the current module. And considering the ring as we are at the top level, it will be the creator itself. And that is actually syntactic sugar. So normally, you have to write this, which is the same but a lot less sexy, let's say, like that. But if you want to do tricking things with the documents, you will have to use it. Most people don't really care about that, and it's fine. So yeah. Actually, ResDoc is very nice tool to discover things that are implemented on your types through your dependencies. It's not only the blankend implementations. So when you implement a trait on a generic type, so for instance, you implement a full trait on every type implementing debug, then obviously all the types you will declare that implement debug will have it. But unless you actually know that in your dependencies, you have one doing that, you won't be able to see it. And ResDocs come in and provide those blankend implementations. It was actually added very recently because we had to target directly the internal compiler of virtual machine, which was pretty tight. And that works pretty well now. And we have also the auto traits. So for instance, send and sync. A few more, but let's remain on those two. So if you have primitive types, there will be at least one of them will be implemented and you will see it directly in the documentation. You don't have to go through your code and just testing. You can see it, which is again very convenient. And it allows you to prevent time loss. So again, to help you on your documentation, ResDoc added the same lint system that Rust has. So now you can use directly lint in ResDoc. And by default, they are just warnings. But you can just deny everything in case you want to provide a framework. It's actually very useful. And the first one is in case you have an item, module, function, script, everything, that is lacking documentation. And the second one is in case you like a code example inside your document, which is something that I'm trying to enforce through all the documentation. So far, not so good. We'll see later. Yeah, so now, beyond documentation. So actually, when you provide and write a code example inside your documentation, they are tested when you run a ResDoc. So for instance, in here, if you run cargo test, cargo again, all the code examples inside will be run. So in here, you will have your code failing in case you run it. But since you have no run tag on your code example, it will be not when just tested as it does it compile. But it's tested. Thanks to that, you can actually have a lot less of or how to say, an API test to be sure that everything is up to date. And at the same time, you can provide documentation. So it's a big time. You earn a lot of time once again. Very convenient. And that's something we worked on a lot lately. You have a lot more commands and tags that you can use on the code example. So I will come back to this a bit later. So like I said, when you want to run doc test, if you want to run specifically the doc test, you just cargo test dash, dash, doc. And only the doc test will be run. If you run cargo test, it will be also all the tests actually. Everything marked as shebang, paran, and test. So like I said, you have more tags. So in case you are currently writing your code, there are APIs that aren't stable yet, you can use a URL file, which allows you to fail, obviously. If you want to be, if you are writing a pro or macro, you can use CompileFail to check that some code is specifically failing, which once again is very convenient in case you wanted to provide some nice errors to the users. And if the rising is the rest editions, we had to handle that as well in the rest. So you can specify, I don't want to support, I don't want it to be tested into the last edition. So put it into the 2015. That's fine. You can ignore, because you don't want it to be tested or anything. You just want to have it. To be noted that actually CompileFail and Ignore are marked into the documentation as such. So the CompileFail is marked with a big red running like it's supposed to fail. And Ignore is just like, it's not run. So it's like, whatever. So NoRun doesn't run the test, but it compiles it. It's very convenient when you have IO, for instance. The rest one actually isn't mandatory at all. But it's always nice to specify that it's a rest code block. But like I said, by default, if not specified, it will be rest. So it's not very useful in itself. And the should panic is actually, in case you run, you want it to panic. If you don't panic, it's a failure. And everything else, like for instance, if you have a block with a markdown text or everything, it will be interpreted as another language string. So if your language is called should panic, it will have an issue. Besides that, it will be fine. But that's not all. So I worked a lot on making a rest doc work with no JavaScript. So if you don't have JavaScript, you will have a very not so good looking page rendering. But you will have it. Everything will be available. It will work. The search. So you can search through the rest of the documentation of your crate. It doesn't require a search. It doesn't require an internet connection. It works locally. It's JavaScript. The downside is that we have a pretty big search index. But at least it works without internet. So if you don't have JavaScript enabled, it won't work, obviously. Like I said, you don't need the internet connection, which is something I'm really strongly enforcing, because a lot of people would like to have, for instance, external search with the pro and cons, everything, and some more JavaScript bigger, like Ember frameworks. So the beta is going. You have a source code viewer. And I will go back a bit on this one later. For now, it's pretty simple. I'm starting to make it more nice and user friendly. And the goal here is mostly to allow people to have direct mapping on the UCA function. You can click on SRC. You will go to the definition, and you can see how it's actually implemented. Now you also have the whole file tree and everything. So you can go through the files and everything. So what I was seeing about the source code viewer was that currently it's very simple. You just have a syntax highlighting. And it'd be nice to be able, for instance, when you hover a type, to be able to see where it's used and where it's defined. Remains to be done, and we have a lot of debates on how it should look like. And a lot of things have to be still determined. We're not so sure yet how it would be looked like. But a lot of things are going there in a not so long. So I was seeing the settings too. The settings allow you to have a more precise browsing experience. For instance, some people asked for the first element, when you have a search with only one result, they wanted to go, it was called get lucky or something. And if you have only one result, it will go to this result without any search page rendering on anything. Again, they earn time like that. I'm not so sure, but whatever. A lot of people were complaining that the types definition, when it's available, was collapsed by default. We now allow people to pick exactly which types they wanted to be collapsed or not. And a lot of other settings are there. And mostly, the settings appear when we have a huge debate with not so much people taking one side precisely when we don't know really if people want it by default or not. So we just make a new setting, and that's pretty much it. Something I was pushing for a long time, the Sims, were merged a few years ago. And now you can actually add your own Sim, which is pretty convenient. And you have some rules to follow, like you have to implement all the CSS rules as they have. Otherwise, you won't be able to add it, and it will be just an error at the compiler. But you can add your own Sims. It's pretty simple. And as most feature, at some point, I should write the documentation on how to actually do it. That's it. And customizable, actually, you can pretty much change everything through the command line, adding your own style files on CSS, JavaScript, HTML, even if you want. And I don't know if people know the ponies created on dox.erase, but at some point, you should take a look. It's interesting. Let's say that. And the goal of this was the origin to be able to allow to have more specific experience. Everything that users might want. For instance, if you wanted your documentation to look more like a book than a documentation, we didn't see much people actually use it, except, of course, the standard library and stuff that I'm doing myself. So at some point, yeah. I think what the likes there is, once again, documentation, which is kind of ironic. So very quickly, what's coming next? Like I said, more interactive source code viewer. The automatic click generation, Ben, is on the type name. For instance, you just put a string, and it will render the link for the string. You don't have to do it yourself anymore. More output format supported. So this comes from people were debating about how the pages should look like. And to fix this issue, I proposed to generate JSON as well as HTML. So it's ongoing, and it's taking a lot of time. We now have a conditional documentation. So you can just say, if I'm on this platform, I don't want this thing to be a documentary for some reason. And now the problem is on cargo. And I need to go back on this later. And with the doc aliases, which is for now only used on the STD library. So for instance, if you're looking for the upper hand, you will have the reference page, which will be returned in the search. Yeah. You see it perfectly. Thank you.
 So as I said, you will have to use a lot of your imagination.  And when I say things, just try to have it in your mind or something.  So it will be a ResDoc Beyond Democumentation.  You can enjoy it.  So first, why am I here?  So I'm the ResDoc team leader since recently.  I'm also part of the documentation team, the docs.res team,  and the dev tools team.  So you kind of see some kind of pattern, I think, I think, point.  So I've started working on ResDoc in 2015, I think.  So since then, a lot of things have happened.  And my main focus currently is ResDoc and more globally  documentation.  So I have to work on docs.res and a bit everything, a dot related.  So I tried to show how we were able to provide documentation.  And most things that we have, which are pretty nice now.  So first, what is ResDoc?  So ResDoc is a tool provided alongside the compiler and cargo,  which is used to generate a documentation, as you may guess.  You can do a bit more, but we'll go back to that later on.  I think it's kind of most.  So that's ResDoc.  So raising ResDoc, as you can, you have to mind it.  But you can use it multiple ways, like directly through ResDoc  and you give it a file and it works.  But when you start having dependencies,  it's getting a bit tricky.  And the command line is getting quite long.  So welcome back to make file error.  Is it on?  It's blinking.  Blinking.  OK.  Yeah, so now you can stop having in your mind.  Just read.  So like I was saying, you can use it directly  through the command line.  Or you can use cargo doc, which is making things much simpler.  So you don't have to mind about all the dependencies  and everything.  You just cargo doc and everything is done in the background.  And that's pretty nice.  And you can even have your web browser open.  And going to your page, to your documentation,  just add the dash dash open.  And that's pretty much it.  It's very convenient.  So yeah, fun fact.  That's something we used for some who don't know it.  We have error indexes.  And you can, well, we needed to have something  to generate a Macdon page.  So ResDoc can actually render and convert the Macdon  from two HTML.  So if at some point you need a convert,  it works pretty well.  So documenting.  We tried to focus on having documentation done as much  inside the code as possible.  Because in most languages, the documentation and the code  is generally split.  And you have to rely on tools that are not official.  In ResDoc, we had the look that some people came in pretty  early, just took the compiler AST and converted it into HTML.  So to do so, you can have the documents like that.  So slash slash dash, no, not dash.  Bang.  Bang.  Exactly.  Exclamation mark is to document the current module.  And if you just put slash slash slash,  it's to document the following item.  So in here, it will be the function.  And the previous one will be for the current module.  And considering the ring as we are at the top level,  it will be the creator itself.  And that is actually syntactic sugar.  So normally, you have to write this, which is the same but a  lot less sexy, let's say, like that.  But if you want to do tricking things with the  documents, you will have to use it.  Most people don't really care about that, and it's fine.  So yeah.  Actually, ResDoc is very nice tool to discover things that  are implemented on your types through your dependencies.  It's not only the blankend implementations.  So when you implement a trait on a generic type, so for  instance, you implement a full trait on every type  implementing debug, then obviously all the types you  will declare that implement debug will have it.  But unless you actually know that in your dependencies,  you have one doing that, you won't be able to see it.  And ResDocs come in and provide those  blankend implementations.  It was actually added very recently because we had to  target directly the internal compiler of  virtual machine, which was pretty tight.  And that works pretty well now.  And we have also the auto traits.  So for instance, send and sync.  A few more, but let's remain on those two.  So if you have primitive types, there will be at least  one of them will be implemented and you will see it  directly in the documentation.  You don't have to go through your code and just testing.  You can see it, which is again very convenient.  And it allows you to prevent time loss.  So again, to help you on your documentation,  ResDoc added the same lint system that Rust has.  So now you can use directly lint in ResDoc.  And by default, they are just warnings.  But you can just deny everything in case you want to  provide a framework.  It's actually very useful.  And the first one is in case you have an item, module,  function, script, everything, that is lacking  documentation.  And the second one is in case you like a code example  inside your document, which is something that I'm trying  to enforce through all the documentation.  So far, not so good.  We'll see later.  Yeah, so now, beyond documentation.  So actually, when you provide and write a code example  inside your documentation, they are tested when you run  a ResDoc.  So for instance, in here, if you run cargo test, cargo  again, all the code examples inside will be run.  So in here, you will have your code failing in case you  run it.  But since you have no run tag on your code example, it will  be not when just tested as it does it compile.  But it's tested.  Thanks to that, you can actually have a lot less of  or how to say, an API test to be sure that everything is up  to date.  And at the same time, you can provide documentation.  So it's a big time.  You earn a lot of time once again.  Very convenient.  And that's something we worked on a lot lately.  You have a lot more commands and tags that you can use on  the code example.  So I will come back to this a bit later.  So like I said, when you want to run doc test, if you want to  run specifically the doc test, you just cargo test dash,  dash, doc.  And only the doc test will be run.  If you run cargo test, it will be also all the tests  actually.  Everything marked as shebang, paran, and test.  So like I said, you have more tags.  So in case you are currently writing your code, there  are APIs that aren't stable yet, you can use a URL  file, which allows you to fail, obviously.  If you want to be, if you are writing a pro or macro, you  can use CompileFail to check that some code is  specifically failing, which once again is very convenient  in case you wanted to provide some nice errors to the  users.  And if the rising is the rest editions, we had to  handle that as well in the rest.  So you can specify, I don't want to support, I don't  want it to be tested into the last edition.  So put it into the 2015.  That's fine.  You can ignore, because you don't want it to be tested  or anything.  You just want to have it.  To be noted that actually CompileFail and Ignore are  marked into the documentation as such.  So the CompileFail is marked with a big red running like  it's supposed to fail.  And Ignore is just like, it's not run.  So it's like, whatever.  So NoRun doesn't run the test, but it compiles it.  It's very convenient when you have IO, for instance.  The rest one actually isn't mandatory at all.  But it's always nice to specify that it's a  rest code block.  But like I said, by default, if not specified, it will be  rest.  So it's not very useful in itself.  And the should panic is actually, in case you run, you  want it to panic.  If you don't panic, it's a failure.  And everything else, like for instance, if you have a block  with a markdown text or everything, it will be  interpreted as another language string.  So if your language is called should panic, it will have  an issue.  Besides that, it will be fine.  But that's not all.  So I worked a lot on making a rest doc work with no  JavaScript.  So if you don't have JavaScript, you will have a very  not so good looking page rendering.  But you will have it.  Everything will be available.  It will work.  The search.  So you can search through the rest of the documentation of  your crate.  It doesn't require a search.  It doesn't require an internet connection.  It works locally.  It's JavaScript.  The downside is that we have a pretty big search index.  But at least it works without internet.  So if you don't have JavaScript enabled, it won't  work, obviously.  Like I said, you don't need the internet connection, which  is something I'm really strongly enforcing, because a  lot of people would like to have, for instance, external  search with the pro and cons, everything, and some more  JavaScript bigger, like Ember frameworks.  So the beta is going.  You have a source code viewer.  And I will go back a bit on this one later.  For now, it's pretty simple.  I'm starting to make it more nice and user friendly.  And the goal here is mostly to allow people to have direct  mapping on the UCA function.  You can click on SRC.  You will go to the definition, and you can see how it's  actually implemented.  Now you also have the whole file tree and everything.  So you can go through the files and everything.  So what I was seeing about the source code viewer was that  currently it's very simple.  You just have a syntax highlighting.  And it'd be nice to be able, for instance, when you hover  a type, to be able to see where it's used and where it's  defined.  Remains to be done, and we have a lot of debates on how it  should look like.  And a lot of things have to be still determined.  We're not so sure yet how it would be looked like.  But a lot of things are going there in a not so long.  So I was seeing the settings too.  The settings allow you to have a more precise browsing  experience.  For instance, some people asked for the first element, when  you have a search with only one result, they wanted to go,  it was called get lucky or something.  And if you have only one result, it will go to this  result without any search page rendering on anything.  Again, they earn time like that.  I'm not so sure, but whatever.  A lot of people were complaining that the types  definition, when it's available, was collapsed by default.  We now allow people to pick exactly which types they  wanted to be collapsed or not.  And a lot of other settings are there.  And mostly, the settings appear when we have a huge  debate with not so much people taking one side precisely  when we don't know really if people want it by default or  not.  So we just make a new setting, and that's pretty much it.  Something I was pushing for a long time, the Sims, were  merged a few years ago.  And now you can actually add your own Sim, which is  pretty convenient.  And you have some rules to follow, like you have to  implement all the CSS rules as they have.  Otherwise, you won't be able to add it, and it will be just  an error at the compiler.  But you can add your own Sims.  It's pretty simple.  And as most feature, at some point, I should write the  documentation on how to actually do it.  That's it.  And customizable, actually, you can pretty much change  everything through the command line, adding your own  style files on CSS, JavaScript, HTML, even if you  want.  And I don't know if people know the ponies created on  dox.erase, but at some point, you should take a look.  It's interesting.  Let's say that.  And the goal of this was the origin to be able to allow to  have more specific experience.  Everything that users might want.  For instance, if you wanted your documentation to look  more like a book than a documentation, we didn't see  much people actually use it, except, of course, the  standard library and stuff that I'm doing myself.  So at some point, yeah.  I think what the likes there is, once again, documentation,  which is kind of ironic.  So very quickly, what's coming next?  Like I said, more interactive source code viewer.  The automatic click generation, Ben, is on the  type name.  For instance, you just put a string, and it will  render the link for the string.  You don't have to do it yourself anymore.  More output format supported.  So this comes from people were debating about how the  pages should look like.  And to fix this issue, I proposed to generate JSON as  well as HTML.  So it's ongoing, and it's taking a lot of time.  We now have a conditional documentation.  So you can just say, if I'm on this platform, I don't want  this thing to be a documentary for some reason.  And now the problem is on cargo.  And I need to go back on this later.  And with the doc aliases, which is for now only used on  the STD library.  So for instance, if you're looking for the upper hand,  you will have the reference page, which will be returned  in the search.  Yeah.  You see it perfectly.  Thank you.
rust_rustdoc_0_143.png rust_rustdoc_144_443.png rust_rustdoc_444_1523.png rust_rustdoc_1524_2231.png rust_rustdoc_2232_2735.png rust_rustdoc_2736_2795.png rust_rustdoc_2796_2867.png rust_rustdoc_2868_2951.png rust_rustdoc_2952_3023.png rust_rustdoc_3024_3095.png rust_rustdoc_3096_3239.png rust_rustdoc_3240_3287.png rust_rustdoc_3288_3335.png rust_rustdoc_3336_4343.png rust_rustdoc_4344_5003.png rust_rustdoc_5004_6707.png rust_rustdoc_6708_7127.png rust_rustdoc_7128_9263.png rust_rustdoc_9264_10487.png rust_rustdoc_10488_12227.png rust_rustdoc_12228_12755.png rust_rustdoc_12756_15851.png rust_rustdoc_15852_23375.png rust_rustdoc_23376_25223.png rust_rustdoc_25224_25451.png rust_rustdoc_25452_25570.png