I see your points. It's just that right now, for better or for worse, we
just document functions in paragraph form, often "documenting" multiple
arguments in a single sentence. Maybe this is not good style. But it is a
common practice in the IRanges/GenomicRanges/etc vein. Maybe having
something like roxygen would help us get around those types of habits.

Michael

On Fri, Nov 11, 2011 at 7:57 AM, Steve Lianoglou <
mailinglist.honeypot@gmail.com> 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@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@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@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
>

	[[alternative HTML version deleted]]