rustdoc support for per-parameter documentation

[kvark]

It appears to me that this pattern of documenting function parameter has become an informal standard:

    /// Supplies a new frame to WebRender.
    ///
    /// Non-blocking, it notifies a worker process which processes the display list.
    ///
    /// Note: Scrolling doesn't require an own Frame.
    ///
    /// Arguments:
    ///
    /// * `document_id`: Target Document ID.
    /// * `epoch`: The unique Frame ID, monotonically increasing.
    /// * `background`: The background color of this pipeline.
    /// * `viewport_size`: The size of the viewport for this frame.
    /// * `pipeline_id`: The ID of the pipeline that is supplying this display list.
    /// * `content_size`: The total screen space size of this display list's display items.
    /// * `display_list`: The root Display list used in this frame.
    /// * `preserve_frame_state`: If a previous frame exists which matches this pipeline
    ///                           id, this setting determines if frame state (such as scrolling
    ///                           position) should be preserved for this new display list.
    pub fn set_display_list(
        &mut self,
        epoch: Epoch,
        background: Option<ColorF>,
        viewport_size: LayoutSize,
        (pipeline_id, content_size, display_list): (PipelineId, LayoutSize, BuiltDisplayList),
        preserve_frame_state: bool,
) {...}

It's quite sub-optimal currently for a number of reasons:

• have to repeat argument names
• separate block of argument docs versus arguments themselves
• just a lot of noise

So not only it's not exactly most convenient, it's also easy to get the docs de-synchronized from the code (notice the document_id above ^). It would be much better if we could do this instead:

    /// Supplies a new frame to WebRender.
    ///
    /// Non-blocking, it notifies a worker process which processes the display list.
    ///
    /// Note: Scrolling doesn't require an own Frame.
    pub fn set_display_list(
        &mut self,
        /// Unique Frame ID, monotonically increasing.
        epoch: Epoch,
        /// Background color of this pipeline.
        background: Option<ColorF>,
        /// Size of the viewport for this frame.
        viewport_size: LayoutSize,
        /// The ID of the pipeline that is supplying this display list,
        /// the total screen space size of this display list's display items,
        /// and the root Display list used in this frame.
        (pipeline_id, content_size, display_list): (PipelineId, LayoutSize, BuiltDisplayList),
        /// If a previous frame exists which matches this pipeline id,
        /// this setting determines if frame state (such as scrolling position)
        /// should be preserved for this new display list.
        preserve_frame_state: bool,
) {...}

Does that sound remotely possible? With an assumption that the latter case would produce near-identical documentation to the former.

[steveklabnik]

I am not aware of any sort of "standard" for documenting arguments. We don't generally do this in the standard library.

[kvark]

@steveklabnik I was under wrong impression then, thanks for correcting me. There is still value, I think, to support properly documented function arguments.

[mathijshenquet]

Perhaps it is possible to reuse intra rustdoc links syntax for this. We could include the arguments of a function in its rustdoc scope. Using implied reference links, arg below would be resolved to the argument of the function.

/// [`arg`]: some arg
fn example(arg: u32) {

}

Similar to paramref in C# xml documentation.

[mathijshenquet]

Although this would not be per-argument documentation, it would fix the de-syncing docs issue while being a relatively lightweight addition to rustdoc.

[GuillaumeGomez]

It could interesting. However a big problem remains: what should it look like, both in input and ouput? (markdown side and html side.)

[QuietMisdreavus]

I'm a fan of trying to get per-argument doc comments. Having a finer-grain set of documentation than "the entire function" provides a hook for people to write more docs.

The thing we'll have to solve first is to get doc comments to actually work on function arguments:

/// function docs
fn asdf<
    /// typaram docs
    Asdf: Display
>(
    /// function arg docs
    // ~^ ERROR: expected pattern, found `/// function arg docs`
    thing: Asdf
) -> String {
    format!("{}", thing)
}

Using an unsugared #[doc = "function arg docs"] attribute also doesn't work. However, the type parameter attribute doesn't receive a complaint. However, i'm pretty sure that none of these elements have their attributes tracked in the compiler right now, so that will have to be parsed out and loaded before rustdoc can use them.

---

As for how to display it, that's another matter. For bare functions, it's not a stretch that we can add headings to that page (it's currently empty except for the main docs). For associated functions or trait functions, it gets hairier. We currently don't have any precedent for adding headings underneath a generated item (like a function), so anything we add will be new ground. However, it's possible to just print the "whole function" docs, then add headings for anything we have docs for (i.e. don't add argument/typaram listings for functions that haven't added fine-grain docs for them). At least, that's my initial idea, and the one i would try if/when we get the docs to load in the first place.

[QuietMisdreavus]

One thing i would be interested in seeing (and this may become a lang-team question) is whether/how we can add an attribute to the return type of a function, to possibly document that separately.

[estk]

The feature request as proposed by @kvark is brilliant! I think it fits very nicely with rust's pragmatic view of language design.

• This seems like a significant reduction to the friction of writing docs.
• A standard would benefit the reader in more quickly finding the desired section of the doc.
• It could enhance the richness of the generated documentation.

Bottom line for me is that good docs are critical and this seems to encourage both creation and consumption.

[rklaehn]

My two cents:

I don't mind this feature, but I just wanted to say that I love the fact that documenting every argument individually is not done frequently in the rust docs. In my experience with other languages where documenting every argument with a line of explanation is encouraged or even enforced by a linter, that leads to really pointless documentation since often it is completely obvious from the name of the argument what it is for.

I very much prefer a few sentences explaining the function and reference to the argument names using arg only where it makes sense...

[sivizius]

It could interesting. However a big problem remains: what should it look like, both in input and ouput? (markdown side and html side.)

we could use definition lists for that:

<dl>
  <dt><code>arg</code></dt><dd>Something</dd>
  <dt><code>very_long_arg</code></dt><dd>Something else</dd>
  <dt><code>long_arg</code></dt><dd>Foobar</dd>
</dl>

and with css this could be aligned like this (without bullet points and with correct alignment)

•                   arg – Something
• very_long_arg – Something else
•          long_arg – Foobar

[Dragonrun1]

I think @mathijshenquet idea of using implied reference links is a good one and using <dl> list like @sivizius suggested would be the way to go in html with this once the other details are worked out. It wasn't mentioned but one of the <h2> - <h6> headers should be used before the actual <dl> list with Arguments as the title.

That's my 2 cents anyway and I hope to see this added soon.

[camelid]

We could of course just use the @param syntax used in JS Doc and other documentation systems.

Whatever syntax we use, personally I think the No. 1 reason to implement some kind of per-argument docs system that rustdoc understands is that we could add diagnostics so that they never go stale if an argument is removed. I just ran into this and opened a PR to fix it (#80103) but that wouldn't have ever happened if rustdoc gave an error when documentation refers to an argument that doesn't exist.

[camelid]

@jyn514 Why did you apply the A-attributes label?

[jyn514]

Rather than adding special syntax, I would rather just accept doc-comments on the parameters themselves:

    /// Supplies a new frame to WebRender.
    ///
    /// Non-blocking, it notifies a worker process which processes the display list.
    ///
    /// Note: Scrolling doesn't require an own Frame.
    pub fn set_display_list(
        /// Target Document ID.
        &mut self,
        /// The unique Frame ID, monotonically increasing.
        epoch: Epoch,
        /// The background color of this pipeline.
        background: Option<ColorF>,
        /// The size of the viewport for this frame.
        viewport_size: LayoutSize,
        /// * `pipeline_id`: The ID of the pipeline that is supplying this display list.
        /// * `content_size`: The total screen space size of this display list's display items.
        /// * `display_list`: The root Display list used in this frame.
        (pipeline_id, content_size, display_list): (PipelineId, LayoutSize, BuiltDisplayList),
        /// If a previous frame exists which matches this pipeline
        /// id, this setting determines if frame state (such as scrolling
        /// position) should be preserved for this new display list.
        preserve_frame_state: bool,
    )

Then there's no need for special HTML or markdown syntax, it's very clear what text applies to which parameters just by looking at it. I added A-attributes because like QuietMisdreavus mentioned, it will require support from the parser to accept attributes in those positions: #57525 (comment)

I don't mind this feature, but I just wanted to say that I love the fact that documenting every argument individually is not done frequently in the rust docs. In my experience with other languages where documenting every argument with a line of explanation is encouraged or even enforced by a linter, that leads to really pointless documentation since often it is completely obvious from the name of the argument what it is for.
I very much prefer a few sentences explaining the function and reference to the argument names using arg only where it makes sense...

I agree that this shouldn't be the encouraged form of documentation, but I think it would be nice to at least make it possible to write (for the same reason that /// is the de facto standard but it's still possible to use /**).

[jyn514]

Whatever syntax we use, personally I think the No. 1 reason to implement some kind of per-argument docs system that rustdoc understands is that we could add diagnostics so that they never go stale if an argument is removed. I just ran into this and opened a PR to fix it (#80103) but that wouldn't have ever happened if rustdoc gave an error when documentation refers to an argument that doesn't exist.

This isn't an issue if the syntax is on the argument itself - you'd know when you remove the argument to remove the documentation, because it's right there staring you in the face.

[personalizedrefrigerator]

Perhaps it is possible to reuse intra rustdoc links syntax for this. We could include the arguments of a function in its rustdoc scope. Using implied reference links, arg below would be resolved to the argument of the function.

/// [`arg`]: some arg
fn example(arg: u32) {

}

Similar to paramref in C# xml documentation.

This is also what Dart does. I think it would be quite nice to have.

[tigregalis]

Would love this.

It is already called out as a future possibility in RFC 2565: Attributes in formal function parameter position

[jyn514]

The next step here is for someone to make a lang team MCP or RFC. It is not something rustdoc can do on its own.

[thurn]

The useful part about this for me in languages that support it, like C# and Java, is that you can create a linter which detects when you mention a function parameter that does not exist. This helps keep documentation up-to-date when functions change.

[cheater]

What if instead I prefer

    pub fn set_display_list(
        &mut self,
        epoch: Epoch,                  /// Unique Frame ID, monotonically increasing.
        background: Option<ColorF>,    /// Background color of this pipeline.
        viewport_size: LayoutSize,     /// Size of the viewport for this frame.
        (pipeline_id, content_size, display_list): (PipelineId, LayoutSize, BuiltDisplayList),
          /// ^ The ID of the pipeline that is supplying this display list,
          /// the total screen space size of this display list's display items,
          /// and the root Display list used in this frame.
        preserve_frame_state: bool,
          /// ^ If a previous frame exists which matches this pipeline id,
          /// this setting determines if frame state (such as scrolling position)
          /// should be preserved for this new display list.
) {...}

Many people do comments like that

[cheater]

linter

this can work with the format presented in the original post that OP doesn't like (it is, in fact, many people's preferred way of doing things)

[tigregalis]

What if instead I prefer

    pub fn set_display_list(
        &mut self,
        epoch: Epoch,                  /// Unique Frame ID, monotonically increasing.
        background: Option<ColorF>,    /// Background color of this pipeline.
        viewport_size: LayoutSize,     /// Size of the viewport for this frame.
        (pipeline_id, content_size, display_list): (PipelineId, LayoutSize, BuiltDisplayList),
          /// ^ The ID of the pipeline that is supplying this display list,
          /// the total screen space size of this display list's display items,
          /// and the root Display list used in this frame.
        preserve_frame_state: bool,
          /// ^ If a previous frame exists which matches this pipeline id,
          /// this setting determines if frame state (such as scrolling position)
          /// should be preserved for this new display list.
) {...}

Many people do comments like that

This suggestion covers your first case, I think in a more rustic way:

pub fn f(
    a: u32, //! Parameter A
    b: u32, //! Parameter B
) { ... }

As for your second case, that's the first time I've seen that, what language or ecosystem is that common in? Other than the obscurity, I think there is value in consistency within the language and between users of Rust. By that I mean there should be one good way of doing things.

[cheater]

@tigregalis what suggestion do you have for argument comments that require multiple lines?

[tigregalis]

You go above the line you're commenting, as in the original post, and in perfect alignment with existing Rust documentation syntax. To be clear the suggestion is that the ///-before syntax and //!-after syntax could be compatible, and largely consistent with existing Rust syntax.

I think something that's obvious but no one has specifically mentioned here, are the parallels to documenting a struct.

You can easily imagine this:

    /// Supplies a new frame to WebRender.
    ///
    /// Non-blocking, it notifies a worker process which processes the display list.
    ///
    /// Note: Scrolling doesn't require an own Frame.
    pub struct DisplayListSetter {
        /// Unique Frame ID, monotonically increasing.
        epoch: Epoch,
        /// Background color of this pipeline.
        background: Option<ColorF>,
        /// Size of the viewport for this frame.
        viewport_size: LayoutSize,
        /// The ID of the pipeline that is supplying this display list,
        /// the total screen space size of this display list's display items,
        /// and the root Display list used in this frame.
        (pipeline_id, content_size, display_list): (PipelineId, LayoutSize, BuiltDisplayList),
        /// If a previous frame exists which matches this pipeline id,
        /// this setting determines if frame state (such as scrolling position)
        /// should be preserved for this new display list.
        preserve_frame_state: bool,
    }

Being roughly equivalent to this:

    /// Supplies a new frame to WebRender.
    ///
    /// Non-blocking, it notifies a worker process which processes the display list.
    ///
    /// Note: Scrolling doesn't require an own Frame.
    pub fn set_display_list(
        &mut self,
        /// Unique Frame ID, monotonically increasing.
        epoch: Epoch,
        /// Background color of this pipeline.
        background: Option<ColorF>,
        /// Size of the viewport for this frame.
        viewport_size: LayoutSize,
        /// The ID of the pipeline that is supplying this display list,
        /// the total screen space size of this display list's display items,
        /// and the root Display list used in this frame.
        (pipeline_id, content_size, display_list): (PipelineId, LayoutSize, BuiltDisplayList),
        /// If a previous frame exists which matches this pipeline id,
        /// this setting determines if frame state (such as scrolling position)
        /// should be preserved for this new display list.
        preserve_frame_state: bool,
) {...}

[newpavlov]

Note that Rust also supports inner (/*! ... */) and outer (/** ... */) block doc comments. Though they are rarely used in practice. So in theory one could write something like this:

fn foo(
    arg1: u32, /*! First arg
                   Second line
                   Third line */  
) { ... }

Though personally I would strongly prefer to use multiline /// comments instead.

[swfsql]

@tigregalis I also think that's a good model, but there are quite some corner cases, such as when there are generics on the parameters (including for impl Traits, trait items and Self references). For Self, in the struct it would refer to the new struct not to the original one, and this is specially important when some trait bounds types must be defined to Self. Finally, the function may also have generics and bounds, which would also make the struct being generic, have the same bounds and so on.

For example:

    /// Doc.
    pub fn f(
        /// Doc.
        a: Self
    ) {...}

    /// Doc.
    pub struct FSetter {
        /// Doc.
        a: Self, // <- should not refer to `FSetter`
    }

[sivizius]

/// vs. //!, like #[…] vs. #![…], is not before vs. after but rather before-a-block and inside-a-block. There is no after-a-block. Like struct Foo {} //^ This is a foo is not possible, arg: Arg, //! This is an argument, neither on the same line nor with a linebreak, is ›rustic‹. Yes, this is a somewhat arbitrary restriction, but ensures expectations. I do not want to have to figure out first to which a comment is referring to. In rust-code, I can assume that comments are always before the item the comment is about. IMHO, doc-comments on arguments must behave exactly the same as doc-comments on struct-fields.

[MultisampledNight]

Do I understand correctly that the best way forward seems to be an RFC for attributes on function arguments? If so, I'd want to write one (having never written one but needing this for other reasons).
This would be very nice for macro reasons, too, currently function arguments are the only publicly exposed named items that aren't allowed to be doc-commented or marked with other attributes.

note: only recently re-discovered this comment, completely forgot about it. i'll still try to do it though

[MultisampledNight]

(minor nit: fwiw I guess the title should be about parameters instead, not arguments? arguments would be the actual value passed at runtime i think)

[ghost]

Just ran into this myself. Does anybody know which things would have to be modified in order to implement the initial proposal? (or has it already been implemented in a nightly?)

[eggyal]

Do I understand correctly that the best way forward seems to be an RFC for attributes on function arguments?

That's correct (it's not that that's "the best way" so much as it's a necessity for any change to the surface syntax of the language, which this would amount to).

If so, I'd want to write one (having never written one but needing this for other reasons).

Make sure you first read carefully and follow the instructions in the Rust RFC Book and review the discussion here (especially @scottmcm's comment above: amongst other things, they're a member of the lang team that must approve the RFC).

[geo-ant]

Please feel free to delete this comment if this is not the right place to talk about this. I have released the roxygen crate which exposes an attribute macro to document function parameters and generic arguments. It can maybe act as a polyfill until this lands upstream.

[eugenesvk]

Not to mention that having them per-argument is horrible whenever they're at all related to each other. It's way nicer to be able to say "draw a rectangle from the top left corner (x0, y0) to the bottom-right corner (x1, y1)" rather than having some annoying

@param x0 the x coordinate of the top-left corner of the rectangle to draw
@param y0 the y coordinate of the top-left corner of the rectangle to draw
@param x1 the x coordinate of the bottom-right corner of the rectangle to draw
@param y1 the y coordinate of the bottom-right corner of the rectangle to draw

This is entirely self-inclicted verbosity, the following would work even better than your single sentence since it visually highlights the difference between the "0=top and 1=bottom" labels due to the fact that the names are vertically aligned:

fn draw_rect ( /// draw a rectangle, accepting x,y coordinates for two corners
@param x0 ↖    top-left  corner
@param y0   ..
@param x1 ↘ bottom-right corner
@param y1   ..
) {}

[eugenesvk]

Your example is worse, x,y is more readable than going full words, so doesn't diminish the need of per-par docs even in this simplistic example

You'd need something like this for the nirvana of self-documentation and instant visual recognition , but Rust blocks this beauty

fn draw_rect ( // draw a rectangle accepting coords for 4 edges
←, →,
↑ ,↓,
// or if you think in corners
// draw a rectangle accepting coords for 2 corners
x↖, y↖,
x↘, y↘,
) {}

[cheater]

apparently github is hell bent on mangling that comment, so here it is again:

fn draw_rect ( /// draw a rectangle accepting coords for vertical and horizontal edges
@param left_edge
@param top_edge
@param right_edge
@param bottom_edge
) {}

sure you can write pathological code in any setting, but the above example shows you that you can write code here which is almost entirely self-documenting.

this was what eugene was replying to here:

Your example is worse, x,y is more readable than going full words

Well, since you gave no argument to why it's worse, I'll just say this: "It's not", and I will also not provide any arguments. Great! Both sides have provided no arguments.

[eugenesvk]

I gave an argument, it's right there in your quote: "more readable than going full words" in the same way fn is vs function_with_parameters, so now that I've pointed out the argument explicitly, go ahead and try to say that x/y for coordinates is worse than words

[cheater]

"It's not because going full words is more readable than going single letters"

[maia-s]

All that's being asked for here is the possibility of documenting function parameters in a consistent way. I don't think anybody's arguing for making this required if it were to be added. Some things might be better documented as part of the overall function documentation, and this feature doesn't change that.

In fact, I'd very much like to have this feature, but I'd like to suggest that the missing_docs lint should not trigger on undocumented function parameters by default. There could be another lint for that if people want it.

[ryanpeach]

Your example is worse, x,y is more readable than going full words, so doesn't diminish the need of per-par docs even in this simplistic example

You'd need something like this for the nirvana of self-documentation and instant visual recognition , but Rust blocks this beauty

fn draw_rect ( // draw a rectangle accepting coords for 4 edges
←, →,
↑ ,↓,
// or if you think in corners
// draw a rectangle accepting coords for 2 corners
x↖, y↖,
x↘, y↘,
) {}

@eugenesvk This is lovely! In a "never in production" sort of way XD.

@cheater I'll provide an argument from a very specific subdomain: mathematics and algorithms. It's very common that people want to program a companion to a paper using the same variable names as the variables in the paper. It makes it easier to read the paper inline with the code. And like it or not, math and algorithm papers use a lot of single letter variable notation.

I think @maia-s is exactly right. This is not a requirement, and the lint should be by default "allow". But you can manually set it to "warn" if you want, or do it case-by-case.

[MultisampledNight]

(fyi: even though i'm still interested in tackling this, realistically i'll only get around to this in a few months? so if anyone else might be faster, feel free to pick this up and write an RFC!!)

[cheater]

@ryanpeach why are you arguing with me? I'm literally one of the first few people who supported adding this.