I can think of some specific cases where doc comments on variables would be useful. Sometimes I use a comment to document some important context or conditions that don't easily fit in a variable name:
// How many cats to remove at the end of the session.
// Invariant: Must be less than or equal to `cats_added` at all times.
let mut cats_to_remove = 0;
If this were a doc comment, and my IDE or editor displayed it on hover and during auto-completion, it would make the comment easier to consult whenever the variable is referenced later in the function.
This would be almost entirely a tooling change, requiring no new language features. I see little downside to this, since it just takes existing comments and potentially makes them more useful. (On the other hand, looking at existing projects that I contribute to, comments that would benefit from this are not terribly common.)
Another use case would be doc comments on function parameters, as proposed in #57525:
pub unsafe fn from_raw_parts<'a, T>(
/// Pointer to the first element of the slice.
data: *const T,
/// The number of `T` elements in the slice.
len: usize,
) -> &'a [T]
This could be used by IDEs and editors, as well as rustdoc. It has some advantages over JavaDoc style (where the argument list is duplicated in the documentation) or current rustdoc style (where there is no way to directly document a specific parameter). Doc comments on parameters could be:
- Easy to write (no need to replicate the list of parameters in prose),
- Easy to read (you don't need to scan some other location if you wonder “what does this parameter mean?”),
- Easy to maintain (harder to forget to update the docs when the list of parameters changes), and
- Useful for tooling (for example, your IDE could show documentation for the specific parameter you are currently entering).
(Of course, like variables, not every parameter needs documentation beyond its name and type. I expect this would be used mainly for functions with fairly complex signatures, or cases where a parameter has important invariants or significance not conveyed by the name alone.)