[R] Block comments in R?

[Duncan Murdoch]

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