[R] Block comments in R?

[hadley wickham]

> 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)

Hadley