> - 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/
_______________________________________________
Roxygen-devel mailing list
Roxygen-devel@lists.r-forge.r-project.org
https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel
