From kjetilh@umsanet.edu.bo  Thu Dec 12 18:45:07 2002
From: kjetilh@umsanet.edu.bo (kjetil halvorsen)
Date: Thu Dec 12 18:45:07 2002
Subject: [Rd] Flat documentation?
References: <5.0.2.1.0.20021211143041.02872480@mcmail.cis.mcmaster.ca> <b5vcvu0tp8ab3r1o9r9m9c1rqv4rke2llp@4ax.com> <3DF7571E.20E2B822@bank-banque-canada.ca> <5.0.2.1.0.20021211143041.02872480@mcmail.cis.mcmaster.ca> <8e3hvu4rvnimgh0bu798itlcbhhdeuv1c2@4ax.com> <5.1.0.14.2.20021212092533.01ddb880@mcmail.cis.mcmaster.ca> <qbbhvu825pgqghjjn76cj8q8kckknda02l@4ax.com>
Message-ID: <3DF8C951.FB17F34A@umsanet.edu.bo>

Hola!


Duncan Murdoch wrote:
.
.
.

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

When functions are stored in workspaces, and options keep.source=FALSE
are used, it will not work to write the documentation as comments in the
function. So attributes seems preferable, if one goes for 
light-weight documentation.

Kjetil Halvorsen


> 
> 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
> 
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> http://www.stat.math.ethz.ch/mailman/listinfo/r-devel



[Rd] Flat documentation?
kjetil halvorsen