Flat documentation?

On Thu, 12 Dec 2002 09:35:40 -0500, you wrote in message
<5.1.0.14.2.20021212092533.01ddb880@mcmail.cis.mcmaster.ca>:

Dear Duncan,

At 09:18 AM 12/12/2002 -0500, Duncan Murdoch wrote:

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.

I can think of several ways to store a multi-line text attribute: a vector
of strings, a string with new-line characters, etc. It would be easiest to
import the text from a file, and it would be up to help() to display the
information correctly.

Storage isn't a problem, I'm thinking of the user interface.  I
normally write my functions in a text editor, then source them into R.
Other people use a workspace as the primary place to store functions.
Both methods should allow for easy addition of lightweight
documentation.

One problem with using embedded comments is that people don't agree on
the One True Comment Style.  For example, I wrote a Turbo Pascal
language parser once that built help files from comments in Pascal
source, and I found it very useful.  However, when I gave it away to
other people, I found that everyone has their own comment style, and
they didn't like the assumptions my parser was making about how to put
the comments into the help file.  For example this sort of problem
(translated into R) came up.  Which style of source should I assume?

Version 1:

 # Add two vectors
 sum <- function(x, y) x+y

 # Subtract two vectors
 diff <- function(x, y) x-y

Version 2:  (This one makes more sense in TP, where you give the
function header in one section, and the implementation in another)

 sum <- function(x, y) x+y
 # Add two vectors

 diff <- function(x, y) x-y
 # Subtract two vectors

Version 3:

 sum <- function(x, y) {
        # Add two vectors
        x+y
  }

 diff <- function(x, y) {
        # Subtract two vectors
        x-y
  }