# [Rd] Flat documentation?

**kjetil halvorsen
**
kjetilh@umsanet.edu.bo

*Thu Dec 12 18:45:07 2002*

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
*