Better description/details when combined

[hadley]

It would be nice to offer tools to automatically generate a description/details/custom section to describe what each function does when you're documenting multiple functions in the same file.

In base R, there's usually a different paragraph for each function in the details, but I think we can do better. Perhaps a custom section that appears where details normal does? Perhaps a bulleted list should be added to details?

[hadley]

There are three common scenarios in which you want to document multiple functions on the same page:

• multiple functions with very similar interface and slightly different results
• documenting methods with class
• documenting methods with generic

These need to be formatted slightly differently:

• details section, list labelled with function name
• "methods" section, list labelled with generic usage
• "methods" section, list labelled with signature

I think this suggests a new tag with two parameters: type and description.

@minidesc name description
@minidesc usage description
@minidesc signature description

This would be readily extensible if I thought of other uses.

[hadley]

Even better:

#' @describeIn class-name Method description
#' @describeIn generic-name Method description
#' @describeIn function-name Method description