/** */ (outer block doc comment)Comment

Explanation

/** ... */ is the block-comment equivalent of /// — it documents the item immediately following it and participates in generated documentation and doc tests the same way, as in /** Adds two numbers together. */ placed directly above a function.

In practice /// is far more idiomatic in the Rust ecosystem and is what rustfmt/community style favors; /** */ is rarely seen in real codebases even though it's fully supported.

Usage examples

Documenting a function

/** <- this block doc comment documents the function immediately below it */
fn add(a: i32, b: i32) -> i32 { a + b }

Restriction: same placement rule as /// — it must sit directly before the item it documents. In practice, prefer /// (see ///); this form exists mostly for completeness.

Documenting an API

/** */ documents an item exactly like /// — the choice between them is purely stylistic, and idiomatic Rust code overwhelmingly picks ///.

/** Parses a duration string like `"5s"` into whole seconds. */
pub fn parse_duration(input: &str) -> Result<u64, ParseError> {
    // <- `/** */` above documents this fn; behaves identically to `///`
    todo!()
}

pub struct ParseError;

rustfmt and community convention treat /// as the default for item docs — see /// for the full treatment (summary/detail shape, doc tests, intra-doc links), all of which apply here unchanged. Reach for /** */ only to match an existing codebase's established style, not for new code.

Explanation

Embedded support: Full

/** ... */ documents the following item identically under #![no_std] — doc generation is a host-side compile step, unaffected by the target having no std. See /// for the fuller embedded-specific discussion (documenting register-level functions, the host-vs-target doc test caveat); everything there applies here unchanged. /// remains the idiomatic choice in embedded crates, same as hosted Rust — this block form is rare.

Usage examples

Documenting a register-level function

/** Sets GPIOA pin 5 high.

Must not be called before `clocks::init()` — GPIOA is unclocked until
then and writes are silently ignored. */
pub unsafe fn set_pin_5_high() {
    // <- `/** */` above documents this fn; identical to `///` in behavior and rendering
    // ...
}