[Roxygen-devel] roxygen2: tag @aliases for S4 method generates quoted aliases

[Hadley Wickham]

> - The tags that one should be to automatically generate are:
> @aliases, @usage, and even the @param for the arguments from the signature
> if no better description is provided by the user in the embedded doc for a
> given method. In such case an sub-itemized list for the argument could be
> created and filled with default doc for the non documented argument types.

I don't think we want to automate parameter documentation - this is
really something that needs to be done by hand, and if filled in
automatically, the user will no longer get a warning when running R
CMD check.

> - however the user should be able to prevent an automated doc to be
> generated by providing an empty tag (e.g an empty tag @usage might be useful
> not to clutter the Rd file with similar usage directives)

I'm not sure about this one - my experience with ggplot2 where many
usage statements were omitted is that this confuses users.  But I'm
not sure how much roxygen should lock people into a certain style of
documentation.

> - As I said in a previous post, the description tag (and other tags) related
> to each method could be concatenated with some separator such as
> "\newline\emph{methodName}: "

I think I forgot to respond to this, but don't like this idea that
much, because there's not an obvious way to override it (to not get
the section heading - which should probably be a subsection anyway).
Secondly, I don't think we should make it too easy for people to
document multiple functions in one file - this is one of the things
that frustrates me most about core R documentation.  Documenting too
many functions in one place makes the documentation much harder to
understand.  My preferred approach is to provide better tools for
reducing duplication across files (e.g. @template, @inheritParams,
@family).

> - a wiki-like syntax could be allowed that would automatically generate the
> different links and other style directives.

We've discussed a little about adding inline tags -
https://github.com/klutometis/roxygen/issues/19.  My feeling that
adopting a plain text formatting system (like markdown) would add
cause problems because you'd either have to insist on one formatting
system (*bold* or \bold{bold}) or build a very complex system to
integrate the two.

> In the end the user will be able to really focus only on the "interesting"
> parts of the documentation, not the binding parts.

Yes, totally agreed!

Hadley


-- 
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/