[Roxygen-devel] S4 documentation

[Steve Lianoglou]

Hi,

Lots of great ideas there.

Just to comment on this one:

On Mon, Nov 14, 2011 at 10:08 AM, Hadley Wickham <hadley at rice.edu> wrote:

>> One last thing: documentation for classes can get pretty long. Is there a
>> way to @include extra files? Steve Lianoglou had this idea.
>
> That's another interesting idea.  We currently have @template, which
> is a superset of @include, but it might be worthwhile differentiating
> them semantically.  Where would you imagine such include files living?
>  Would they be R files or plain text to be interpreted as roxygen
> comments?  (We decided on R files for templates so that existing
> syntax highlighting code would work)

When I floated it on the bioc-devel list, it was simply suggested as a
means to avoid having long encyclopedic like documentation  text take
up the majority of a source file.

That type of documentation is super handy when you actually want to
fire up the help page to explore what this or that method/class does,
but as a developer writing S4-style code, I'd be really happy if I can
just have "the nut" of the documentation there inline w/ the code,
which in my mind includes:

(1) The banner
(2) Description
(3) What each argument is
(4) What is returned

If the usage/details benefits from some long explanation, then it
would be nice to just stash that in an @include `somehting`.

I was imagining it would just be simple text file that follows roxygen
syntax, perhaps w/o having to prefix each line with a #' (or ##' for
the emacs-en).

And perhaps just have that include some file path in a default folder,
maybe PKG/rdox?

So an `@include something/somewhere

Might just include the file
`PKG/rdox/something/somewhere(.rdoxy|.txt|)?` or something ... but
smarter (and more convenient) include schemes could be "schemed up," I
reckon.

Thanks,
-steve

-- 
Steve Lianoglou
Graduate Student: Computational Systems Biology
 | Memorial Sloan-Kettering Cancer Center
 | Weill Medical College of Cornell University
Contact Info: http://cbio.mskcc.org/~lianos/contact