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 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 documentation comment
"Normal" comment
It is a comment as in others programming languages.
Documentation comment
This kind of comment generates documentation to code "below". The comments say, what the sum function does, an Example section and an example of use. In this example area, it is possible to write Markdown code block inside of documentation comment too.
Both are the same:
There are some common sections used in many projects:
- Example
- Panic
- Errors
- Safety
Contained comment
That comment generates code to above. When outer of all, generates documentation to the crate, inside a block of code, for example, create documentation for this block of code.
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 for just to talk about the comments in Rust, and how it is easy to makes documentation from it. I guess it is worth to say that 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.
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 in 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:
Top comments (0)