Re: [R] Block comments in R?

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
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



R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html 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 https://stat.ethz.ch/mailman/listinfo/r-help. Please read the posting guide before posting to the list.