rust_documentation_docs
Rust documentation - docs. version: 1.0.0 date: 2026-06-14 author: bestia.dev repository: codeberg.org
Hashtags: #ready-for-use #tutorial #rust My projects on codeberg.org are more like a tutorial than a finished product: bestia-dev tutorials.
Code documentation
I am as lazy as any programmer. I like to write code, debug and watch my creation come to life.
But I hate writing documentation. I will call the documentation in short as docs.
Docs are boring and soul-crushing. Every change I made in my code makes the docs instantly obsolete and in need of change.
It is a chore!
Workflow before every public release
I want to have nice docs always. Before every public release, I need to correct the docs.
This is the workflow:
- Open the project to the left
- Open
Live Previewof the docs to the right - Activate cargo watch
- Change the md and rs files and confirm visually on the right that it has the desired format
cargo doc
Fortunately, the Rust team knows how important docs are and they made the life of developers somewhat easier.
We write special comments directly inside the code called doc comments. They start with /// for function or type and //! for modules. These same doc comments are also used by VSCode Hover Preview that I like so much.
The doc comments are basically Markdown with some peculiarities.
This command will get all the doc comments and generate a bunch of good-looking HTML pages. It is very fast.
cargo doc
cargo auto doc
I want to add more functionality to the simple cargo doc command. I have a task in automation-tasks-rs that I can modify to my pleasure.
cargo auto doc
Cargo.toml
Cargo.toml contains the most important information about the project: name, description, author, repository,...
I want to copy this information to my Markdown files. I do it in the cargo auto doc task.
README.md
README.md is the first and main page of the repository. That is a good standard, probably started with github.com.
Published crates on crates.io also start with the same README.md file.
I want the first page of the docs to be equal to my readme. Or at least the majority of the text in the README.md.
One of the tasks in automation-tasks-rs is cargo auto doc. It copies most of the content of README.md into the doc comments of the file main.rs or lib.rs, and this makes it the first page of the docs.
Doc comments
Every function or type must have a doc comment.
/// Verify checksum of files in all backups.
pub fn all_verify(atomic_quit: std::sync::Arc<core::sync::atomic::AtomicBool>){
}
If there is only one line, it is simple. This line will be shown everywhere in the docs and in the VSCode Hover Preview. The standard is to write in a 'commanding form' as a whole sentence that ends with a dot.
If we need more lines, it is wise to separate the first line as the title, followed by an empty line and then the content of the description.
/// Initialize tracing to folder `logs/` in filenames like `{APP_NAME_LOG}.{date}.log`.
///
/// The file `.gitignore` contains `logs/` \
/// and therefore will not be committed.
pub fn tracing_init() -> anyhow::Result<()> {
}
newline
Markdown is notoriously bad with newlines. It is so unintuitive.
If we end the line with a normal newline, the Markdown processor will just continue the line. Maybe sometimes it makes sense, but for me, it is just bad design that can never be changed again.
The most official way of doing a newline is making a new paragraph. This is made by adding an empty line in between paragraphs.
But it takes a lot of space, and I don't like it. My texts are docs and not a literary essay. For me, everything is a new soft paragraph. The thoughts are very short and concise. I like the normal newline very much, and it is a pain in Markdown.
The "normal" Markdown uses double space at the end of a line as the signal for newline. This makes it impossible to simply see if the lines have or do not have a newline.
I am discovering that the VSCode Hover Preview does not process the double space at all.
There is another standard that is intrusive but more visible: double space and backslash blahblah. \. Much better. But this backslash must never come at the end of the paragraph before an empty line or at the end of the text. Another thing to have in mind and be distracted when writing.
Why oh why didn't they make it like most normal text processor: make an explicit signal for line continuation and not for newline. Just the opposite. Because the HTML works that way. And Markdown is processed into HTML.
Most of my lines end with a dot if I mean to have a newline there.
In VSCode, I can find using regex all the incorrect lines.
Regex for *.md files:
- line does not start with slash, has text, ends with dot or dot-double-space, the next line is not empty
- line does not start with slash, has text, ends with dot-double-space-backslash, the next line is empty
(^(?!\s*[\/!\[(]).+[.?!):]( )?\n(?!$))|(^(?!\s*[\/!\[(:])(.+[.?!):] \\\n)(?=$))
Regex for *.rs files:
- line starts with /// or //!, have some text, ends with dot or dot-double-space, the next line is a comment with text
- line starts with /// or //!, ends with dot-double-space-backslash, the next line is not a comment or an empty comment line
(^\/\/[\/!].+[.?!):]( )?\n(?=\/\/[\/!].+\n))|(^\/\/[\/!](.+[.?!):] \\\n)(?=([^\/])|(\/\/[\/!]\n)))
Space at the end of the line
The command cargo fmt will erase spaces at the end of the line because it is regularly an error.
You can find it using regex and remove it yourself where cargo fmt does not in all file types:
^.+[ ]+$
Save the find file regex in VSCode
I manually added to "C:\Users\luciano\AppData\Roaming\Code\User\keybindings.json" the shortcut for Ctrl+shift+ć.
{
// key combination: ctrl+k č
// In all normal text processors it is natural to end a sentence with a dot end then ew-line for a new 'soft paragraph'.
// But Markdown has this peculiarity: it just ignores the newline and continues the text.
// To force the newline, you must type 2 spaces and a backslash before the newline. That is contra-intuitive and I forget it a lot.
// And this must never be the end of a line before an empty line or the end of text. So confusing.
// Not to be confused with the real 'hard paragraph' in Markdown that is an empty line in between paragraphs.
// So I made this little search find file. It is not perfect,
// but it will catch most of these type of errors.
// Find in all Markdown *.md files.
// In JSON, the backslash must be escaped as a double backslash.
"key": "ctrl+k oem_1",
"command": "workbench.action.findInFiles",
"args": {
"query": "(^(?!\\s*[\\/!\\[(]).+[.?!):]( )?\\n(?!$))|(^(?!\\s*[\\/!\\[(:])(.+[.?!):] \\\\\\n)(?=$))",
"filesToInclude":"*.md",
"isRegex": true,
"wholeWord": false
}
},
{
// key combination: ctrl+k ć
// In all normal text processors it is natural to end a sentence with a dot end then ew-line for a new 'soft paragraph'.
// But Markdown has this peculiarity: it just ignores the newline and continues the text.
// To force the newline, you must type 2 spaces and a backslash before the newline. That is contra-intuitive and I forget it a lot.
// And this must never be the end of a line before an empty line or the end of text. So confusing.
// Not to be confused with the real 'hard paragraph' in Markdown that is an empty line in between paragraphs.
// So I made this little search find file. It is not perfect,
// but it will catch most of these type of errors.
// Find in all Rust *.rs files.
// In JSON, the backslash must be escaped as a double backslash.
"key": "ctrl+k oem_7",
"command": "workbench.action.findInFiles",
"args": {
"query": "(^\\/\\/[\\/!].+[.?!):]( )?\\n(?=\\/\\/[\\/!].+\\n))|(^\\/\\/[\\/!](.+[.?!):] \\\\\\n)(?=([^\\/])|(\\/\\/[\\/!]\\n)))",
"filesToInclude":"*.rs",
"isRegex": true,
"wholeWord": false
}
},
{
// key combination: ctrl+k š
// A line should never end with a space.
// So I made this little search find file. It is not perfect,
// but it will catch most of these type of errors.
// Find in all files.
// In JSON, the backslash must be escaped as a double backslash.
"key": "ctrl+k oem_4",
"command": "workbench.action.findInFiles",
"args": {
"query": "^.+[ ]+$",
"filesToInclude":"",
"isRegex": true,
"wholeWord": false
}
},
cargo test
Inside doc comments, we can have code blocks just like in Markdown. The Rust team decided that we can check if the Rust code inside is correct when we run cargo test.
If we don't want this check, set the language of the code block to ignore instead of rust.
VSCode Live Preview
Microsoft created a VSCode extension called "Live Preview". It refreshes the browser when the file changes.
In the file explorer, in the context menu, it adds the command "Show Preview". Execute it on an HTML file.
In VSCode, find the file ~/rustprojects/bestia-dev-ready-for-use/bestia-dev-website/var_www_bestia.dev/docs/bestia-dev-ready-for-use/backup_for_luciano/index.html and run 'Show Preview'. It opens a browser inside VSCode.
This is the URL for the docs of 'backup_for_luciano' in VSCode from the folder 'rustprojects'.
Automate cargo auto doc
When I want to edit the docs, I must modify the underlying .rs and .md files.
After every change, I need to run manually cargo auto doc. It is a chore!
We can use cargo-watch to run the command every time a file changes.
With this automation and the refreshing of the browser, we can see the changes to HTML live.
cargo install cargo-watch
echo "Use Ctrl-c to exit cargo-watch."
cargo watch -s "cargo auto doc"
TODO
Nothing comes to mind.
Open-source and free as a beer
My open-source projects are free as a beer (MIT license).
I just love programming.
But I also need to drink. If you find my projects and tutorials helpful, please buy me a beer by donating to my PayPal.
You know the price of a beer in your local bar ;-)
So I can drink a free beer for your health :-)
Na zdravje! Alla salute! Prost! Nazdravlje! 🍻
//bestia.dev
//codeberg.org/bestia-dev
//github.com/bestia-dev
//bestiadev.substack.com
//youtube.com/@bestia-dev-tutorials