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

[Steve Lianoglou]

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