Flat documentation?

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
  }

Duncan Murdoch