[Rd] [R] Function hints

[hadley wickham]

> For me, it's been extremely helpful to keep function & documentation
> together during editing-- it greatly increases the chance that I will
> actually update the doco when I change the code, rather than putting it
> off until I've forgotten what I did. Also, writing Rd format is a
> nightmare (again, personal opinion)-- being able to write plain-text
> makes the whole documentation thing bearable.

I agree!

> The above is not quite to the point of the original post, I think, which
> talks about storing the documentation as commented bits *inside* the
> function code. However, I'm not sure the latter is really desirable;
> there is some merit in forcing authors to write an explicit "Details" or
> "Description" section that is not just a paraphrase of programming
> comments, and such sections are unlikely to fit easily inside code. At
> any rate, I wouldn't want to have to interpret my *own* programming
> comments as a usage guide!

That is what I mean by inline documentation (in the same file),
probably need a better name.  Javadoc uses "doc comments in source
code", rdoc "Generates structured HTML documentation from Ruby
source.", perl: "embedded documentation", php: "standard
auto-documentation tool"...


> WRTO automatic "usage" sections: it is easy to write code to do this
> ('prompt', and there is also some in 'mvbutils'-- not sure if it's in
> the current release though) but at least as far as the "usage" section
> goes, I think people should be "vigorously encouraged" to write their
> own, showing as far as possible how one might actually *use* the
> function. For many functions, just duplicating the argument list is not
> helpful to the user-- a function can often be invoked in several
> different ways, with different arguments relevant to different
> invocations. I think it's good to show how this can be done in the

I write functions that have only one use, and I think having a
function that takes widely different sets of parameters depending on
usage to be a bit of a "code smell" (personally opinion only, of
course)

> My general point here is: the documentating process should be as
> painless as possible, but not more so. Defaults that are likely to lead
> to unhelpful documentation are perhaps best avoided.
> For this general reason, I applaud R's fairly rigid documentation
> standards, even though I frequently curse them. (And I would like to see
> some bits more rigid, such as compulsory "how-to-use-this" documentation
> for each package!)

I agree - making it easy for people to generate useless documentation
is no better than making it hard to generate good documentation.
Reducing the duplication between code and documentation (eg. argument
list) and having sensible defaults (eg. usage section) can go a long
way to making the process much less painful.

Hadley