[Rd] Flat documentation?
John Fox
jfox@mcmaster.ca
Thu Dec 12 17:51:03 2002
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
-----------------------------------------------------