Skip to content

rustdoc support for per-parameter documentation #57525

@kvark

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-attributesArea: Attributes (`#[…]`, `#![…]`)C-feature-requestCategory: A feature request, i.e: not implemented / a PR.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.needs-rfcThis change is large or controversial enough that it should have an RFC accepted before doing it.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions