Re: [R] Block comments in R?

From: Duncan Murdoch <>
Date: Mon 09 Oct 2006 - 17:02:56 GMT

On 10/9/2006 10:06 AM, hadley wickham wrote:

>> Current .Rd documentation has some obvious problems:
>> - the parser strips comments out of examples when it runs them
>> - there's no way to put images into the documentation
>> - the keywords aren't much use
>> - there's isn't a definition anywhere of what the format really is, so
>> it's hard to know
>> whether something will work other than by trying it -- and it may break
>> with the next release.
>> - there's no way to link from a help man page to a vignette or other
>> form of documentation.

> The main thing I don't like about the current system is the amount of
> duplication - you have to supply a lot of information in the
> documentation that is also encoded in the function (ie. everything in
> the codoc check). This makes it unnecessarily painful when updating
> documentation to reflect minor changes. The large distance between
> code and documentation also makes it easy to forget to update the
> documentation when changing the code. These are things that are
> helped by inline documentation (which I am using)

Inline documentation isn't the only way to achieve what you want: better editing tools would help too. I don't know if ESS helps with this, but I could imagine a smart editor would be able to help with the updates in each direction.

The big problem with this solution is that there is such a variety of editors in use, and most people are convinced that everyone else has made a big mistake in choosing theirs.

However, there was talk in the summer about adding more keywords to .Rd files, to expand in various ways. A keyword that expanded to the arg list of a function might be a nice way to avoid duplication. If we had a way to put argument descriptions into the R file it could do a better job, but it would be tricky: e.g. what if the "file" arg in two objects to be documented in the same .Rd had different descriptions? I agree with Richard that we don't want to force separate man pages for every documented object.

Duncan Murdoch mailing list PLEASE do read the posting guide and provide commented, minimal, self-contained, reproducible code. Received on Tue Oct 10 23:19:33 2006

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.1.8, at Tue 10 Oct 2006 - 13:30:12 GMT.

Mailing list information is available at Please read the posting guide before posting to the list.