My Rust journey: Documentation

If you are learning how to code, you already face a documentation of something; a language, framework, library or anything else. So, imagine a world without them, a world where you do not know how a method called send with 1000 lines of code works, but you need to maintenance this code, a world where you need to use a library had built for a random programmer, but you do not make any sense how it works, for that, documentation come to save us.

I admit, I do not have so much expertise with big real world software, but the contact I had, it was only possible because someone takes her/his time to write down and explain how that piece of code works. There are many reasons to write doc to code, but let me contain with these.

Rust and cargo together provide an awesome tool to speed up that process of documentation, what is not common in the majority of programming language. "cargo doc" makes a functional and ready-to-go documentation's page as of the comments inside the code, even though not all comment types does not generate doc.

  • // or /* */ - "normal" comment
  • /// or /** */ - Documentation comment
  • //! or /*! */ - Contained comment

"Normal" comment

It is a comment as in other programming languages.

carbon.png

Documentation comment

This kind of comment generates documentation to code below. Inside this comments kind, it is possible to write Markdown. At first lane says what the sum function does, an Example section, and an example of use. In this example of use, shows to it is possible to write Markdown code block inside of documentation comment.

carbon(1).png

That one works exactly:

carbon(2).png

There are some common sections used in many projects:

  • Example
  • Panic
  • Errors
  • Safety

Contained comment

This other generates code to above. When outer of all, generates documentation to the crate, inside a block of code, as example, create documentation for this one.

carbon(3).png

Cargo and documentation's generation

When all code are documented, it is time to build the documentation page through a cargo command already quoted.

cargo doc

"cargo doc" create a struct of folder in "/target/doc/name-of-crate". In this case, crate's name is my_rust_journey, so...

ruan@Ubuntu:~/Documentos/Dev/Blog/Rust/my_rust_journey$ tree target/doc/
target/doc/
├── ayu.css
├── brush.svg
├── COPYRIGHT.txt
├── dark.css
├── down-arrow.svg
├── favicon-16x16.png
├── favicon-32x32.png
├── favicon.svg
├── FiraSans-LICENSE.txt
├── FiraSans-Medium.woff
├── FiraSans-Regular.woff
├── LICENSE-APACHE.txt
├── LICENSE-MIT.txt
├── light.css
├── main.js
├── my_rust_journey
│   ├── all.html
│   ├── fn.sum.html
│   ├── index.html
│   └── sidebar-items.js
├── normalize.css
├── noscript.css
├── rustdoc.css
├── rust-logo.png
├── search-index.js
├── settings.css
├── settings.html
├── settings.js
├── SourceCodePro-LICENSE.txt
├── SourceCodePro-Regular.woff
├── SourceCodePro-Semibold.woff
├── source-files.js
├── source-script.js
├── SourceSerifPro-Bold.ttf.woff
├── SourceSerifPro-It.ttf.woff
├── SourceSerifPro-LICENSE.md
├── SourceSerifPro-Regular.ttf.woff
├── src
│   ├── blog_documentation
│   │   └── lib.rs.html
│   └── my_rust_journey
│       └── lib.rs.html
├── storage.js
├── theme.js
└── wheel.svg

To verify how the page looks like, run the index.html under the my_rust_journey to visualize the crate doc.

Cargo also provides a way to build the doc and open it automatically in your browser:

 cargo doc --open

That Cargo has many other good tools to learn, but as this blog is just a simple learning note, if something more precise is required, it better goes to the cargo's documentation.

That is it. This one was a small blog just to talk about the comments in Rust, and it is easy to makes documentation from it. It is worth to say, documentation test was not covered because I will write about in another My Rust journey blog what will be about tests. Doc attributes was not too because I will edit a past blog what talks about attributes, and add that content on it.

As I almost completed The Rust Programming Language book, comments could not the best subject to blog, but I do not feel comfortable yet to write about, as example concurrency. As soon as possible I will do blogs about that "tough" themes.

As I say in every blog from this series, this is a learning journal, compacted and suppressed, any wrong information can be reported, what will help so much and the process of learning.

Thanks for reading, and feel free to like, comment, correct me or just say a "hi".

I hope this help someone.

Useful links:

No Comments Yet