[R] Block comments in R?

[Duncan Murdoch]

Rolf Turner wrote:
> I must say I agree with Richard O'Keefe who wrote:
>
>   
>> I wrote:
>>     R documentation comments really belong
>>     in [.Rd] files where help() can find them.
>>
>> Barry Rowlingson <B.Rowlingson at lancaster.ac.uk> replied:
>> 	R documentation comments belong in .Rd files at the moment, but how 
>> 	joyous would it be if they could be included in the .R files?
>> 	
>> How joyous?  About as joyous as a root canal job without anaesthetic.
>>     
>
> 				<etc.>
> 				<snip>
>
> 	(a) I don't speak Python and I don't believe I ever will; I'm
> 	not sure what Python does; I don't want to know.  R does what
> 	I want to do.  I don't want to have to learn Python syntax to
> 	do something with which I am very happy doing the R way
> 	currently.
>   
To be fair, I don't think anyone proposed that.  As I read it, the 
suggestion was to take Python's idea of inline documentation into R, not 
necessarily an identical implementation.
> 	(b) Modularity is a ***Good Thing***.  Code should be code,
> 	documentation should be documentation.  They should click
> 	together but be kept separate.
>   
I tend to like comments in code.  Rd-style documentation has a different 
purpose, but not all that different.  I tend not to put so many comments 
into my R code because I spend the time writing .Rd files, but then it's 
inconvenient to see the docs when I'm working on the code.
> 	(c) The R documentation system is neat, efficient, well
> 	thought out, and well constructed.  It is an intrinsic part
> 	of the nature of R.  (It's one of the --- many --- reasons I
> 	like R better than Splus, which I no longer use.) Changing
> 	the R documentation system to something (Monty?) Pythonesque
> 	would change the nature of R and make it uglier.
>   
I'd rather wait to see an actual proposal before I decided if it was 
uglier or more beautiful.

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.

None of these would be addressed by inline help, but other people may 
have other complaints.  I think it was DSC 2001 where R Core decided to 
replace the .Rd system with something better; I would say it's a 
reasonable prediction that that won't happen soon, but incremental 
improvements to .Rd have happened, and we should think about other ones.

Duncan Murdoch