[Roxygen-devel] inline documentation, R5, and where can I find the examples?

[Hadley Wickham]

>>> Some of my packages use S4 but for the most part I've moved onto R5
>>> reference classes that interface Rcpp and java classes.  Does anyone
>>> have any good examples of documenting an R5 class?
>>
>> I don't.  Have you read ?referenceClasses for John Chambers suggested
>> form of documentation?

> The problem here is that people have to know that the object they have
> is a reference class.  At the moment most users I would wager are
> unaware of the existence of reference classes let alone knowing how to
> obtain documentation from them.  It is a great idea but is new,
> different and not obvious.  There should be way to link to Rd
> Documentation and the internal documentation.

Yes, but this needs to be an R standard, not a roxygen2 standard.
Otherwise it doesn't really help because people still won't know how
to find help!

One possible convention would to be use refclass?method to get help
about a method.  This is somewhat confounded with the existing
standard for getting help about packages (package?mypackage) and S4
classes (class?myclass), but does have a nice parallel with the way
that R5 methods are called.


>> They should all be listed in the help for individual roclets:
>> ?rd_roclet, ?namespace_roclet, ?collate_roclet etc.
>
> The documentation here is very good but does not allow for easy
> scanning of tags.  Also not all tags are represented (eg.
> exportPattern)

If you see any that are missing, please file a bug at
https://github.com/klutometis/roxygen/issues

>>> The second issues that comes from my doxygen experience is if there is
>>> a way that we can extract inline documentation.  From the beginning
>>> roxygen only looked at documentation before a function.  But doxygen
>>> looks at the entire function for comments.  The Google R Coding
>>> standards specifies that the comments be inside the function block.

Note that the Google style guide is effective the Tim Hesterburg style
guide and should not be treated as canonical.

>>> This provides for useful code folding that swallows up the
>>> documentation as well for nice and tidy code.
>>
>> Could you provide an example?
>
> I did provide an example but here is a very simple inline documentation example.
> ```r
> #' @title Addition
> add <- function(
>   x #' @param x a number
>  ,y #' @param y another number
> ){
>  #' @section details
>  #' performs addition of two objects.
>  return x+y #' @return a number that is the sum of x and y
> }
> ```
> This way x and y are documented in place where they are defined, and
> the return value is documented where it is defined.  As far as
> literate programming goes this is the principle that code is
> documented where it is written, as close to where it is written as
> possible.

Personally, I really dislike this style of documentation.  I much
prefer to have all the documentation in one place.  That means that
this isn't something I would spend time working on, but I would accept
a well tested patch that implemented this style.

Hadley


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