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).
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)>
{
...
}
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 :