[R] Rd Files?

[Philippe Grosjean]

>"Wolski" <wolski at molgen.mpg.de> wrotes:
>> I have seen the output and it does not matter to me anymore if prompt
>> or package.skeleton works on any platform. I hope it wasn't a too big
>> heresy.  If someone would ask me what are the week point of R, then
>> the only one that pops up immediately, is that the documentation to
>> functions have to be stored in a separate file than the code.  I am a
>> big R/S fan.  But its a pity that comments above or below the function
>> declaration are not recognized by the help system. Therefore "prompt"

Toni Rossini answered:
>Doug Bates commented on the possibility of patching Doxygen to do
>this, once long ago.  Not sure if anyone took it anywhere, though.
>It's a reasonable system for assisting with documentation in a number
>of languages, though it could be improved.  That would be nice, since
>then one would get C docs "for free".

>Another alternative is to write a noweb lit-prog file, and then generate
>your package via noweb (NOT Sweave, though you get double duty, since
>if it's written right, you can stick the original doc in as a
>vignette).

Well, writing a quick and durty help for a function with a few lines of
comment above or below the function code ("a la Matlab") should be nice. I
don't think that it should be a good idea to provide a complex alternative
solution for documenting the functions than the current mechanism which is
both powerful and efficient (but, of course, a little bit complex). Here is
a "quick and durty" implementation of a mechanism to include "quick and
durty" help messages inside the code of an R function. I guess this is
enough.

qhelp <- function(topic) {
    if (is.character(topic))
        topic <- get(topic)
    if (!is.function(topic))
        stop("`topic` must be a function, or the name of a function")
    fcode <- sub("    ", "", deparse(topic)) # Because 4 spaces are added by
deparse
    # Look for quick help text, that is, strings starting with `#`
    qhlp <- fcode[grep("^\"\#", fcode)]
    qhlp <- as.character(parse(text=qhlp))
    cat(paste(qhlp, "\n", sep=""), sep="")
    return(invisible())

    # Quick help
    "# `qhelp()` provides a mechanism to include \"quick help\""
    "# embedded inside the code of an R function."
    "#"
    "# Just end the function code with return(res)"
    "# and add some strings starting with `#` after it"
    "# with the content of your quick help message..."
}

# An example of a very simple function with quick help
cube <- function(x) {
    # This is some comment that will appear only when I print the
function...
    return(x^3)

    # Quick help
    "# `cube(x)` returns the cube of its `x` argument"
    "# Version 0.1, by Ph. Grosjean (phgrosjean at sciviews.org)"
}

qhelp(cube)    # Should return quick help
qhelp("qhelp") # Strings also allowed for `topic` argument
qhelp("log")   # No quick help, should print just an empty lines

Best,

Philippe

...........]<(({?<...............<?}))><...............................
 ) ) ) ) )
( ( ( ( (   Prof. Philippe Grosjean
 ) ) ) ) )
( ( ( ( (   Numerical Ecology Laboratory
 ) ) ) ) )  Mons-Hainaut University
( ( ( ( (   8, Av. du Champ de Mars, 7000 Mons, Belgium
 ) ) ) ) )
( ( ( ( (   phone: 00-32-65.37.34.97
 ) ) ) ) )  email: Philippe.Grosjean at umh.ac.be; phgrosjean at sciviews.org
( ( ( ( (   SciViews project coordinator (http://www.sciviews.org)
 ) ) ) ) )
.......................................................................