[Bioc-devel] A call for feedback on writing S4 docs with roxygen

[Colin A. Smith]

I just replied to his message:

http://lists.r-forge.r-project.org/pipermail/roxygen-devel/2011-November/000319.html

I've spent a good amount of time working on a large C++ project that made extensive use of Doxygen documentation. Its strengths were in the two things that have been touched on:

1. Quick, inline documentation that can can be formatted into an easy to read HTML form.
2. Understanding the structure of the code in terms of classes/methods, inheritance, namespaces, and call graphs.

For packages in R, I find number 1 to be the most important, especially for keeping code and documentation in sync, like Steve mentions. I also find it really helpful for reading/understanding code to have the documentation right there.

Number 2 is also important. I think that either the HTML help index could be made a lot better in that regard, but that would be more of a R-devel thing. Another alternative would be to put a lot of that information in the not often used xxx-package.Rd pages. I think Roxygen or other packages could definitely grow into that area.

-Colin

On Nov 11, 2011, at 16:57, Steve Lianoglou wrote:

> Hi Michael,
> 
> I think I see where you are coming from.
> 
> I think in (my) ideal world and constrained by the way R is currently
> (normally/"properly") documented, I'd love to be able to put the
> banner/title, description, and argument "junk" inline w/ the source
> code.
> 
> If usage/examples aren't too long, I think they'd fit nicely there too.
> 
> Also keep in mind that you can inline define which functions are
> exported through in the NAMESPACE, and which function you are
> currently writing required to be imported from another package first
> in order to register the base generic def, etc.
> 
> But for docs that are super long, I can see how huge chunks of
> documentation/prose isn't ideal ... perhaps an @include directive (or
> something) that can inline a file that has some long/verbose
> exposition that would reduce the signal:noise ratio in the source
> itself would be nice.
> 
> Maybe it's just me, but the split between the Rd and the source to
> document the "essense" of the function, ie. its params and short
> description is enough of a burden to me that I'm not all that good
> about fishing into the Rd when I change something in my code.
> 
> One could argue that I need to spend more time upfront really
> hammering out the API of whatever I'm working on in my head before I
> hit the pavement/editor. I wouldn't disagree in theory, but in
> practice it's just not how things work out.
> 
> -steve
> 
> On Fri, Nov 11, 2011 at 10:22 AM, Michael Lawrence
> <lawrence.michael at gene.com> wrote:
>> I have spoken with him about this, and I wasn't sure if it was worth it.
>> Much of the documentation we write is pretty free-form. I am not sure how
>> that could be inlined. Maybe it's just the wrong style? Do people really
>> like putting all that documentation into their source code? Literate
>> programming is nice for a data analysis in a vignette, but I'm not so sure
>> about IRanges. Folding might help. What's so bad about Rd anyway? I guess
>> I'm just more of a "use the source, Luke" kind of guy and like direct
>> control over the output.
>> 
>> What would be really nice is a way to generate documentation on methods and
>> classes dynamically, as they are registered. Some sort of alternative to
>> always calling showMethods, getClass, etc.
>> 
>> Michael
>> 
>> On Fri, Nov 11, 2011 at 6:42 AM, Steve Lianoglou
>> <mailinglist.honeypot at gmail.com> wrote:
>>> 
>>> Hi devs,
>>> 
>>> Hadley is in the midst of trying to get roxygen2 to better handle S4
>>> class/methods.
>>> 
>>> I thought there would be some folks here (hi bioc-core) who would be
>>> well suited to give useful feedback given the monumental documentation
>>> in some of the bioconductor packages.
>>> 
>>> If anyone has time to share some feedback, I'm sure it'd make his end
>>> result much better and would be a large boon to the R community at
>>> large, since I think roxygen goes a long way to making writing
>>> documentation a lot less painful :-)
>>> 
>>> Here is his post:
>>> 
>>> http://lists.r-forge.r-project.org/pipermail/roxygen-devel/2011-November/000318.html
>>> 
>>> Cheers,
>>> -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
>>> 
>>> _______________________________________________
>>> Bioc-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>> 
>> 
> 
> 
> 
> -- 
> 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
> 
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel