[Rd] Flat documentation?

Duncan Murdoch murdoch@stats.uwo.ca
Thu Dec 12 16:53:02 2002


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
  }

Duncan Murdoch