[Rd] Flat documentation?

[kjetil halvorsen]

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