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