From dmurdoch@pair.com  Thu Dec 12 15:19:56 2002
From: dmurdoch@pair.com (Duncan Murdoch)
Date: Thu Dec 12 15:19:56 2002
Subject: [Rd] Flat documentation?
In-Reply-To: <5.0.2.1.0.20021211143041.02872480@mcmail.cis.mcmaster.ca>
References: <b5vcvu0tp8ab3r1o9r9m9c1rqv4rke2llp@4ax.com> <3DF7571E.20E2B822@bank-banque-canada.ca> <5.0.2.1.0.20021211143041.02872480@mcmail.cis.mcmaster.ca>
Message-ID: <8e3hvu4rvnimgh0bu798itlcbhhdeuv1c2@4ax.com>

On Wed, 11 Dec 2002 14:42:41 -0500, you wrote:

>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



[Rd] Flat documentation?
Duncan Murdoch