6 exercises — write Rust /// and //! doc comments correctly: rustdoc examples, Panics/Errors sections, and intra-doc links.
0 / 6 completed
1 / 6
You want to document a public Rust function so it appears in the generated rustdoc HTML. Which comment style is correct?
Rust uses `///` (triple slash) for outer documentation comments, which attach to the item immediately below them (a function, struct, enum, etc.) and are picked up by `rustdoc` to generate HTML documentation. Regular `//` comments are invisible to rustdoc — they're just ordinary code comments.
Syntax: /// Parses a config file and returns a validated Config struct. placed directly above pub fn parse_config(...) -> Config { ... }
`///` comments support full Markdown, including code blocks, links, and headers, and are the standard way to document any public API surface in Rust.
2 / 6
You want to document an entire module (the module itself, not a specific item within it) at the top of a `mod.rs` or `lib.rs` file. Which comment syntax is correct?
`//!` (inner doc comment) documents the enclosing item — typically placed at the very top of a file to document the module or crate itself, rather than the item that follows it. This is the key distinction from `///`, which documents the item that comes after it.
Syntax: //! This module handles authentication logic, including token validation and session management. placed at the top of auth/mod.rs, before any `use` statements or items.
`//!` is commonly used at the top of `lib.rs` to document the entire crate — this becomes the crate-level landing page on docs.rs.
3 / 6
A rustdoc comment should include a runnable example. Which is the correct way to add one that also gets tested by `cargo test`?
Rust doc comments support doctests — Markdown fenced code blocks (triple backticks) inside a `///` comment that `cargo test` automatically compiles and runs as real tests. This means documentation examples can never silently go stale; if the API changes and the example breaks, the test suite fails.
Convention: an '# Examples' heading (Markdown `#`) introduces the example section, followed by a fenced code block with runnable Rust code, typically ending in an `assert_eq!` to demonstrate expected behaviour.
This is one of Rust's most distinctive documentation features — "your docs are also your tests."
4 / 6
You are documenting a function that can panic under certain conditions and returns a `Result` that can be an `Err`. Which rustdoc convention correctly documents this?
Rust community convention (and the official API guidelines) reserve specific Markdown headings within `///` doc comments: `# Panics` for conditions that cause a panic, `# Errors` for conditions that produce an `Err` result, and `# Safety` for invariants that must hold when calling `unsafe` functions. These are conventional section names, not enforced by the compiler, but consistently followed across the ecosystem (including the standard library).
Following these conventions makes generated docs immediately scannable — a caller can jump straight to "when does this panic?" without reading the full description.
5 / 6
How should you document a public trait's method to explain what implementors must guarantee, as opposed to what callers should expect?
When documenting a trait method, it's often necessary to address two audiences: callers (what does calling this do?) and implementors (what must my implementation guarantee?). Explicitly calling out implementor obligations — like idempotency, thread-safety, or ordering guarantees — prevents subtle bugs when someone implements the trait without reading the source of other implementations.
Useful phrasing: "Implementors must ensure...", "Callers should not assume...", "This method is expected to..." — these phrases clearly separate the contract for each audience within the same doc comment.
6 / 6
You want cross-references between items in your rustdoc comments — e.g. linking from a function's docs to a related struct. Which is the correct intra-doc link syntax?
Rust supports intra-doc links: writing an item name in square brackets (e.g. [`Config`]) inside a doc comment, and rustdoc automatically resolves it to a link to that item's generated documentation page — including correct path resolution and disambiguation when multiple items share a name.
Syntax: /// See [`Config`] for the full list of options. or, for disambiguation, [`Config`](struct@Config) when a function and struct share a name.
This is preferred over hardcoded URLs because intra-doc links stay correct automatically as the crate's documentation is regenerated, and they're verified at doc-build time — broken links cause build warnings.
What will I practice in "Rust Doc Comments — Code Comments Exercise"?
This is a Code Comments exercise set. It walks through 6 scenario-based multiple-choice questions built around real usage of Code Comments terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 6 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the Code Comments vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more Code Comments exercises?
See the Code Comments exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — Code Comments vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.