[Rd] [R] Function hints

[hadley wickham]

> I think it's bad to document dissimilar functions in the same file, but
> similar related functions *should* be documented together.  Not doing
> this just adds to the burden of documenting them, and the risk of
> modifying only part of the documentation so that it is inconsistent.
> The user also gets the benefit of seeing a common description all at
> once, rather than having to decide whether to follow "See also" links.

I agree - having some kind of include command would mitigate this
problem, but I think many documentation systems have struggled with
this (hard) problem and I'm not aware of any great solutions.

> Your solutions would both be interesting on their own merits regardless
> of the above.  We did decide to work on preprocessing directives for .Rd
> files at the R core meetings; some sort of include directive may be
> possible.

One model to follow might be xinclude
(http://www.w3.org/TR/xinclude/), although I don't really know much
about it apart from a dim awareness of its existance, and being an xml
schema it is probably over complicated.

> I don't think I would want complete documentation mixed with the
> original source, but it would certainly be interesting to have partial
> documentation there.  (Complete documentation is too long, and would
> make it harder to read the source without a dedicated editor that could
> hide it.  Though ESS users may see it as a reasonable requirement to
> have everyone use the same editor, I don't think it is.)  However, this
> is a lot of work, depending on infrastructure that is not in place.

I've attached an example of my own inline documentation system,
modelled closely on javadoc, which I use for documenting my packages.
It took me a few hours to whip up a (ruby) program to turn this into
rdoc files, and wouldn't require too much more time to make more
robust (and rewrite in R for wider distribution).

Having a lot of documentation in your source files does feel strange
at first, but I think you quickly get used to it, and functions with
more code than documentation soon start to look strange.

> I think it is worse than that.  There are concepts in packages that just
> don't arise in base R, and hence there would be no keywords for them
> other than "misc", even if someone redesigned the current system.
> Keywording is hard, and it's not clear to me how to do much better than
> we currently do.

I agree - apart from hiring a dedicated keyword person I can't see
anyway that this is going to improve significantly.

> >  * Some functions aren't documented (eg. simulate.lm, formula.glm) -
> > typically, these are methods where the documentation is in the
> > generic.  Solution: these methods should all be aliased to the generic
> > (by default?), and R CMD check should be amended to check for this
> > situation.  You could also argue that this is a deficiency with my
> > function, and easily fixed by automatically referring to the generic
> > if the specific isn't documented.
>
> I'd say it's a deficiency of your function.  You might want to look at
> the code in get("?") and .helpForCall() to see how those functions work
> out things like
>
> ?simulate(x)

Ok, I can fix my function fairly easily, what should I list - the name
of the function, or what to call to get help?  (or maybe if people
were more aware of the "?simulate(x)" form, it wouldn't be such a
problem.

> >  * Needs wide display to be effective.  Could be dealt with by
> > breaking description in a sensible manner (there may already by R code
> > to do this.  Please let me know if you know of any)
>
> I think strwrap() may do what you want.

That's it - I'll give that a go.

> >  * Personally, I think sentence case is more aesthetically pleasing
> > (and more flexible) than title case.
>
> It's quite hard to go from existing title case to sentence case, because
> we don't have any markup to indicate proper names.  One would think it
> would be easier to go in the opposite direction, but in fact the same
> problem arises:  "van Beethoven" for example, not "Van Beethoven".

Yes, which is why I don't do it automatically - it would be nice to
recommend using sentence case in the R developers guide.

Hadley