Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better description/details when combined #185

Closed
hadley opened this issue Feb 6, 2014 · 2 comments
Closed

Better description/details when combined #185

hadley opened this issue Feb 6, 2014 · 2 comments

Comments

@hadley
Copy link
Member

@hadley hadley commented Feb 6, 2014

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 hadley mentioned this issue Feb 7, 2014
@hadley
Copy link
Member Author

@hadley hadley commented Feb 7, 2014

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
Copy link
Member Author

@hadley hadley commented Feb 11, 2014

Even better:

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

@hadley hadley closed this in 3d6888e Feb 19, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
1 participant