[Rd] Flat documentation?

[John Fox]

Dear Duncan,

At 10:51 AM 12/12/2002 -0500, Duncan Murdoch wrote:
>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.

I was assuming the use of your third style. At present -- in the absence of 
multiline comments -- that would require #ing each comment line at the 
start of the function.

Alternatively, you could create a separate text file, say sum.txt, and 
define the function as:

         sum <- function(x, y) x + y
         doc(sum, "sum.txt")

[or sum <- doc(sum, "sum.txt") for an implementation of doc() without side 
effects.]

Either method should work whether functions are kept in text files or in 
saved workspaces.

>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
>   }

Regards,
  John

-----------------------------------------------------
John Fox
Department of Sociology
McMaster University
Hamilton, Ontario, Canada L8S 4M4
email: jfox@mcmaster.ca
phone: 905-525-9140x23604
web: www.socsci.mcmaster.ca/jfox
-----------------------------------------------------