rustdoc support for per-argument documentation

[kvark]

It appears to me that this pattern of documenting function arguments 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.