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

[Renaud Gaujoux]

On 16/08/2011 18:15, Hadley Wickham wrote:
>> - 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.
I agree with this for the case of standard functions,
however in the case of S4 generic functions the arguments that are part 
of the signature can easily generate an informative parameter documentation.
This will indeed make R CMD check not warn about these (that's the 
point), but a note could still be output by roxigenise if parameters 
were automatically generated. This will make the user aware of them, who 
could check if he's fine with generated documentation.
>> - 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.
One could enable this feature only if a tag like @autodoc is present, 
but I think that, at least for some of the required and standard tags, a 
default style could be more helpful than constraining.
The user is free to do lots of creative things in custom sections, 
examples, etc...
For example Doxygen-generated documentation is customisable but provides 
a default standard style, with auto-filled fields, whenever possible.
>> - 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).
>
I agree that big documentation files are tricky to read, and I like the 
tags @family, @template and @inheritParams.
However I find it useful to find the documentation of very related 
functions into a single file, as you quickly have at hand a description 
of all the utilities that you can use for your specific problem. It 
often shows you functions you did not know and really want to use.
I found this often preferable to using seealso links, especially when 
working in the console under Unix where you cannot click and follow the 
link (when it is there, as many docs only include the name not as a 
link, I guess because it is longer to write \code{\link{fun2}} than 
simply fun2. Wiki syntax could help here.)

Again S4 methods get in the way:
I think that having the documentation for S4 methods of the same generic 
function in a single file, the same as the generic definition if 
possible, is also better that in separate files. The corresponding 
required alias for a S4 method is something like 
"myfun,numeric,matrix-method", which is way too long to type in the 
console, beside the fact that user is not supposed to know which method 
exist for the generic. The user knows the generic "myfun" and by typing 
"?myfun" one expects to get all the relevant information about the 
available methods.
Moreover, for a given generic, S4 methods allow for treating differently 
different input type. These often eventually call the same method that 
really does the job. They then possibly wrap things up specifically for 
the input type.
Having their documentation in separate files would make things both less 
clear and more difficult to maintain.

S4 documentation is something a painful indeed... this is why it would 
nice to make it easy.
Looking at what the function promptMethods does could give some directions.
>> - 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.
>
Not sure to understand why one cannot mix the styles. Having all *bold* 
replaced by \bold{bold} would not bother the already formatted \bold 
tags, would it?

>> 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!
yes, and it will hopefully be integrated into R core at some point, 
since there are already functions like package.skeleton, that does the 
job. An empty skeleton is nice, but a full body would be better... :)

Renaud
> Hadley
>
>

 

###
UNIVERSITY OF CAPE TOWN 

This e-mail is subject to the UCT ICT policies and e-mail disclaimer published on our website at http://www.uct.ac.za/about/policies/emaildisclaimer/ or obtainable from +27 21 650 9111. This e-mail is intended only for the person(s) to whom it is addressed. If the e-mail has reached you in error, please notify the author. If you are not the intended recipient of the e-mail you may not use, disclose, copy, redirect or print the content. If this e-mail is not related to the business of UCT it is sent by the sender in the sender's individual capacity.

###