Rfcs: Documentation: function/method parameter lists

Created on 25 Feb 2017  路  3Comments  路  Source: rust-lang/rfcs

I was working to clarify the meaning of some parameters in someone else's project and suddenly realized there was no explicit way to document this aspect of the code.

My stop-gap attempt is to drop a bullet list into the long description, but it might be nice to have special handling around this.

/// Draws the given `Drawable` object to the screen.
///
/// * `ctx` - The `Context` this graphic will be rendered to.
/// * `drawable` - The `Drawable` to render.
/// * `quad` - A portion of the drawable to clip.
/// * `dest` - the position to draw the graphic expressed as a `Point`.
/// * `rotation` - orientation of the graphic in radians.
///
pub fn draw(ctx: &mut Context,
            drawable: &mut Drawable,
            quad: Rect,
            dest: Point,
            rotation: f32)
            -> GameResult<()> {
    drawable.draw(ctx, quad, dest, rotation)
}

In a language like Python, documenting parameters has greater importance since it provides hints to the expected types, but it still offers a good opportunity to discuss usage of, and how incoming values contribute to a result.

class Client(object):

    def __init__(self, url, api, mappers=None, default_chunk_size=200):
        """
        :param str url: full url to the atlas instance.
        :param str api: the api version to use.
        :param dict mappers: mapper classes to use for the element types
                             named in the keys.
        :param int default_chunk_size: sets the cursor limit for times when it
                                       is not being explicitly set by the
                                       caller.
        :raises atlas.exceptions.ServerCompatError: if server url is for an
                                                    incompatible server
                                                    version.
        """
        # ...

While having this info show up in the docs, this could also be leveraged in tooling (IDEs, etc).

T-doc

Most helpful comment

I think /// and //! are interpreted in terms of items, but one could imaging tweaking that so that this parsed and did something nice :

/// Draws the given `Drawable` object to the screen.
pub fn draw(
        /// The `Context` this graphic will be rendered to.
        ctx: &mut Context,
        /// The `Drawable` to render.
        drawable: &mut Drawable,
        quad: Rect, //! A portion of the drawable to clip.
        dest: Point, //! the position to draw the graphic expressed as a `Point`.
        rotation: f32 //! orientation of the graphic in radians.
        ) -> GameResult<(
            u64,  //! `x` distance drawn
            u64,  //! `y` distance drawn
        )>
{
    drawable.draw(ctx, quad, dest, rotation)
}

All 3 comments

h/t to @jonathandturner for suggesting I file this! Thanks for the push.

I think /// and //! are interpreted in terms of items, but one could imaging tweaking that so that this parsed and did something nice :

/// Draws the given `Drawable` object to the screen.
pub fn draw(
        /// The `Context` this graphic will be rendered to.
        ctx: &mut Context,
        /// The `Drawable` to render.
        drawable: &mut Drawable,
        quad: Rect, //! A portion of the drawable to clip.
        dest: Point, //! the position to draw the graphic expressed as a `Point`.
        rotation: f32 //! orientation of the graphic in radians.
        ) -> GameResult<(
            u64,  //! `x` distance drawn
            u64,  //! `y` distance drawn
        )>
{
    drawable.draw(ctx, quad, dest, rotation)
}

Would love to see this for function parameters as well as macro parameters.

I would also prefer to see parameter documentation above the item rather than inline. If a specific parameter has a very long comment this breaks up the function signature making it difficult to read:

/// Draws the given `Drawable` object to the screen.
pub fn draw(
    /// The `Context` this graphic will be rendered to.
    ctx: &mut Context,
    /// The `Drawable` to render. This is going to be a very very very
    /// long docstring. With many sentences. Many many sentences.
    ///
    /// Maybe even a second paragraph.
    drawable: &mut Drawable,
) -> GameResult<(u64, u64)>
{
    ...
}
Was this page helpful?
0 / 5 - 0 ratings

Related issues

emk picture emk  路  59Comments

steveklabnik picture steveklabnik  路  183Comments

pnkfelix picture pnkfelix  路  69Comments

pnkfelix picture pnkfelix  路  253Comments

Ekleog picture Ekleog  路  204Comments