Intermediate
Code Comments
#rust
#rustdoc
Rust Doc Comments
6 exercises — write Rust /// and //! doc comments correctly: rustdoc examples, Panics/Errors sections, and intra-doc links.
0 / 23 completed
1 / 23
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:
placed directly above
`///` comments support full Markdown, including code blocks, links, and headers, and are the standard way to document any public API surface in Rust.
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 / 23
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:
placed at the top of
`//!` is commonly used at the top of `lib.rs` to document the entire crate — this becomes the crate-level landing page on docs.rs.
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 / 23
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
This is one of Rust's most distinctive documentation features — "your docs are also your tests."
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 / 23
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.
Following these conventions makes generated docs immediately scannable — a caller can jump straight to "when does this panic?" without reading the full description.
5 / 23
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.
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 / 23
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.
Syntax:
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.
[`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.
7 / 23
During a code review for the `OrderProcessing` module, Emily points out that John's PR introduces a new function, `validate_shipping_address`, which checks if an address is valid. The comment for this function currently states:
/// Validates the shipping address against our database. Mark, the team lead, asks John to revise the comment to explain *why* validation is necessary and what happens if the address is invalid – emphasizing that it's not just about checking a format. Which of the following best represents Mark's request for improved documentation?The core issue here is that rustdoc comments are most effective when they explain the *purpose* and *context* behind code. Simply stating 'Validates the shipping address' doesn't tell a developer *why* this validation matters – perhaps it prevents fraud, ensures delivery accuracy, or complies with regulations. Mark is asking John to add details about the reasoning (e.g., 'to ensure accurate order fulfillment') and potential outcomes (e.g., 'returns an error if the address is invalid').
8 / 23
During a code review for the `UserService` module, Alex notes that Ben's PR introduces a new function, `user_profile_update`, which handles updates to user profiles. Ben has added a rustdoc comment to this function stating:
/// Updates a user profile with the provided data. Alex suggests Ben expand the documentation to clarify what validation is performed on the input data and how potential errors are handled. Which of the following options best reflects Alex's feedback regarding the use of rustdoc comments?Alex is advocating for *comprehensive* documentation, a key principle of good code reviews. The original comment is functional but lacks crucial details that would help developers understand the function's robustness and potential issues. While a brief description can be a starting point, adding information about validation and error handling demonstrates proactive thinking regarding potential problems – this aligns with best practices for robust API design and makes the function easier to use and maintain. The ideal option reflects this emphasis on clarity and completeness.
9 / 23
You're reviewing a PR for the `AuthService` module. Alice has added a new function, `authenticate_user`, which takes a username and password and returns a JWT token on success or an error if authentication fails. The rustdoc comment for this function currently reads: `/// Authenticates a user against our database`. During the review, Bob suggests you ask Alice to add more detail to the documentation. Which of the following options best represents Bob's feedback regarding the use of rustdoc comments in this context?
// Authenticates a user against our database
The initial comment is accurate in describing the *purpose* of the function but lacks crucial context. Bob's feedback highlights a critical omission: specifying which database is queried – this information is vital for developers to understand potential performance implications or dependency issues. Rustdoc comments should provide both purpose and relevant technical details for effective usage.
10 / 23
During a code review for the `OrderProcessing` module, Emily points out that John's PR introduces a new function, `validate_shipping_address`, which checks if an address is valid. The comment for this function currently states:
/// Validates the shipping address against our database. Mark, the team lead, asks John to revise the comment to explain *why* validation is necessary and what happens if the address is invalid – emphasizing that it's not just about checking a format. Which of the following best represents Mark's request for improved documentation?The core issue here is that rustdoc comments are most effective when they explain the *purpose* and *context* behind code. Simply stating 'Validates the shipping address' doesn't tell a developer *why* this validation matters – perhaps it prevents fraud, ensures delivery accuracy, or complies with regulations. Mark is asking John to add details about the reasoning (e.g., 'to ensure accurate order fulfillment') and potential outcomes (e.g., 'returns an error if the address is invalid').
11 / 23
During a code review for the `UserService` module, Alex notes that Ben's PR introduces a new function, `user_profile_update`, which handles updates to user profiles. Ben has added a rustdoc comment to this function stating:
/// Updates a user profile with the provided data. Alex suggests Ben expand the documentation to clarify what validation is performed on the input data and how potential errors are handled. Which of the following options best reflects Alex's feedback regarding the use of rustdoc comments?Alex is advocating for *comprehensive* documentation, a key principle of good code reviews. The original comment is functional but lacks crucial details that would help developers understand the function's robustness and potential issues. While a brief description can be a starting point, adding information about validation and error handling demonstrates proactive thinking regarding potential problems – this aligns with best practices for robust API design and makes the function easier to use and maintain. The ideal option reflects this emphasis on clarity and completeness.
12 / 23
You're reviewing a PR for the `AuthService` module. Alice has added a new function, `authenticate_user`, which takes a username and password and returns a JWT token on success or an error if authentication fails. The rustdoc comment for this function currently reads: `/// Authenticates a user against our database`. During the review, Bob suggests you ask Alice to add more detail to the documentation. Which of the following options best represents Bob's feedback regarding the use of rustdoc comments in this context?
// Authenticates a user against our database
The initial comment is accurate in describing the *purpose* of the function but lacks crucial context. Bob's feedback highlights a critical omission: specifying which database is queried – this information is vital for developers to understand potential performance implications or dependency issues. Rustdoc comments should provide both purpose and relevant technical details for effective usage.
13 / 23
During a code review for the `OrderProcessing` module, Emily points out that John's PR introduces a new function, `validate_shipping_address`, which checks if an address is valid. The comment for this function currently states:
/// Validates the shipping address against our database. Mark, the team lead, asks John to revise the comment to explain *why* validation is necessary and what happens if the address is invalid – emphasizing that it's not just about checking a format. Which of the following best represents Mark's request for improved documentation?The core issue here is that rustdoc comments are most effective when they explain the *purpose* and *context* behind code. Simply stating 'Validates the shipping address' doesn't tell a developer *why* this validation matters – perhaps it prevents fraud, ensures delivery accuracy, or complies with regulations. Mark is asking John to add details about the reasoning (e.g., 'to ensure accurate order fulfillment') and potential outcomes (e.g., 'returns an error if the address is invalid').
14 / 23
During a code review for the `UserService` module, Alex notes that Ben's PR introduces a new function, `user_profile_update`, which handles updates to user profiles. Ben has added a rustdoc comment to this function stating:
/// Updates a user profile with the provided data. Alex suggests Ben expand the documentation to clarify what validation is performed on the input data and how potential errors are handled. Which of the following options best reflects Alex's feedback regarding the use of rustdoc comments?Alex is advocating for *comprehensive* documentation, a key principle of good code reviews. The original comment is functional but lacks crucial details that would help developers understand the function's robustness and potential issues. While a brief description can be a starting point, adding information about validation and error handling demonstrates proactive thinking regarding potential problems – this aligns with best practices for robust API design and makes the function easier to use and maintain. The ideal option reflects this emphasis on clarity and completeness.
15 / 23
You're reviewing a PR for the `AuthService` module. Alice has added a new function, `authenticate_user`, which takes a username and password and returns a JWT token on success or an error if authentication fails. The rustdoc comment for this function currently reads: `/// Authenticates a user against our database`. During the review, Bob suggests you ask Alice to add more detail to the documentation. Which of the following options best represents Bob's feedback regarding the use of rustdoc comments in this context?
// Authenticates a user against our database
The initial comment is accurate in describing the *purpose* of the function but lacks crucial context. Bob's feedback highlights a critical omission: specifying which database is queried – this information is vital for developers to understand potential performance implications or dependency issues. Rustdoc comments should provide both purpose and relevant technical details for effective usage.
16 / 23
During a code review for the `OrderProcessing` module, Emily points out that John's PR introduces a new function, `validate_shipping_address`, which checks if an address is valid. The comment for this function currently states:
/// Validates the shipping address against our database. Mark, the team lead, asks John to revise the comment to explain *why* validation is necessary and what happens if the address is invalid – emphasizing that it's not just about checking a format. Which of the following best represents Mark's request for improved documentation?The core issue here is that rustdoc comments are most effective when they explain the *purpose* and *context* behind code. Simply stating 'Validates the shipping address' doesn't tell a developer *why* this validation matters – perhaps it prevents fraud, ensures delivery accuracy, or complies with regulations. Mark is asking John to add details about the reasoning (e.g., 'to ensure accurate order fulfillment') and potential outcomes (e.g., 'returns an error if the address is invalid').
17 / 23
During a code review for the `UserService` module, Alex notes that Ben's PR introduces a new function, `user_profile_update`, which handles updates to user profiles. Ben has added a rustdoc comment to this function stating:
/// Updates a user profile with the provided data. Alex suggests Ben expand the documentation to clarify what validation is performed on the input data and how potential errors are handled. Which of the following options best reflects Alex's feedback regarding the use of rustdoc comments?Alex is advocating for *comprehensive* documentation, a key principle of good code reviews. The original comment is functional but lacks crucial details that would help developers understand the function's robustness and potential issues. While a brief description can be a starting point, adding information about validation and error handling demonstrates proactive thinking regarding potential problems – this aligns with best practices for robust API design and makes the function easier to use and maintain. The ideal option reflects this emphasis on clarity and completeness.
18 / 23
You're reviewing a PR for the `AuthService` module. Alice has added a new function, `authenticate_user`, which takes a username and password and returns a JWT token on success or an error if authentication fails. The rustdoc comment for this function currently reads: `/// Authenticates a user against our database`. During the review, Bob suggests you ask Alice to add more detail to the documentation. Which of the following options best represents Bob's feedback regarding the use of rustdoc comments in this context?
// Authenticates a user against our database
The initial comment is accurate in describing the *purpose* of the function but lacks crucial context. Bob's feedback highlights a critical omission: specifying which database is queried – this information is vital for developers to understand potential performance implications or dependency issues. Rustdoc comments should provide both purpose and relevant technical details for effective usage.
19 / 23
During a code review for the `PaymentService` module, David asks you to improve the documentation for the `process_payment` function. Currently, the comment states: `This function processes payments using Stripe`. Which of the following is the most effective revision of this comment, considering best practices for Rust Doc?
The original comment is too vague and doesn't convey any technical detail or potential risks. Option A provides more specific information about the API interaction and security. Options B & C are acceptable but less descriptive than option A. Option D is simply a description of integration, not what the function *does*.
20 / 23
Sarah in #dev-team posted this Slack message: 'Ben needs to add more detail to the docs for `user_settings_sync`. It's currently just saying it 'updates user settings'. What should Ben include in his rustdoc comment to fulfill best practices?"
Ben's comment needs to clearly explain *how* the synchronization happens. Option A is the most precise description, detailing the interaction with the database. Options B & C are too general. Option D only describes the *storage* of settings, not their synchronization.
21 / 23
You're drafting a PR description for a change to the `DataValidation` module. The new function, `is_valid_email`, validates email addresses. The current PR description reads: 'This function checks if an email is valid.' Which of the following statements best describes how you should improve this PR description using rustdoc comments?
The original description is too simplistic. Option A provides a technical detail about the validation method (regex and RFC). Options B & C are vague. Option D is similar to option B but lacks specificity regarding the underlying mechanism.
22 / 23
During your daily stand-up, Mark mentions that he's working on improving the documentation for the `RateLimiter` module. He says: 'I'm adding a rustdoc comment to the `new_rate_limit` function.' What is the primary purpose of this comment?
The primary goal is to clearly define the *interface* – what parameters the function accepts and what it does with them. Options A & B focus on implementation details (the algorithm or expected behavior), which are better documented elsewhere. Option C describes integration, and option D is a high-level overview.
23 / 23
You're reviewing a PR for the `ReportingService` module. Lisa has added a rustdoc comment to the function `generate_daily_report`. The comment states: 'This function generates a report of user activity.' Which of the following additions would most significantly improve this comment, aligning with Rust Doc best practices?
The original comment is too abstract. Option A provides specific details about the data source (database query), processing steps (formatting into PDF), and output format. Options B & C are still high-level. Option D only describes a single calculation, not the entire report generation process.
Frequently Asked Questions
What will I practice in "Rust Doc Comments — Code Comments Exercise"?
This is a Code Comments exercise set. It walks through 23 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 23 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.