Flat documentation?

I wonder, however, whether the following simple suggestion might prove 
useful: Suppose that help(foo) and ?foo first look for standard 
documentation. If such documentation exists, it would be processed as at 
present. If there is no standard documentation on foo, then help and ? 
would look for a "doc" attribute of foo (or for initial comment lines in 
the function definition, if foo is a function), and, if this exists, 
display the contents in a pager.

I think that would be an ideal solution, as long as there was a
relatively easy way to import text.  For example, if it's done with
comments (which would be my preference), there should be a way to
enter multi-line comments (like /* ...  */ in C).  If it's done with
attributes there needs to be an easy way to put free-form text into
the attribute.

As an aside, I wasn't certain that multi-line comments didn't exist,
so I checked the language reference.  Comments aren't documented at
all! (At least in the r-devel version...) This should probably be
fixed. I've submitted draft text as a bug report. 



Duncan Murdoch