Hi there Petr,

Apologies for only replying to your post now - I hope the code included
below helps you out.

An alternative function documentation approach would be the one I took when
faced with a
similar problem - I wrote some functions to allow me to embed a retrievable
function specification
into the head of any function I wrote. The code is included below.

How to use this code:
Put the function described below (extractFunctionDefinition) in a single
file (I keep it in
FunctionDescription.R) and load this file at the start of every R project
you wish to use it.

--------------------------------------------------------------START
FUNCTION--------------------------------------------------------------------
extractFunctionDefinition<-function(function_name,start_flag="#<-BEGIN-FUNCTION-DESCRIPTION-BLOCK->",
end_flag="#<-END-FUNCTION-DESCRIPTION-BLOCK->")
{
    #<-BEGIN-FUNCTION-DESCRIPTION-BLOCK->
    # Extracts this function description from a function.
    #
    # Declared In:
    #   FunctionDescription.R
    #
    # Args:
    #   function_name: The name of the function (as a string)
    #   start_flag: Flag (as a string) indicating the start of the function
description block
    #               (default is #<-BEGIN-FUNCTION-DESCRIPTION-BLOCK->)
    #   end_flag: Flag (as a string) indicating the end of the function
description block
    #                (default is #<-END-FUNCTION-DESCRIPTION-BLOCK->)
    #
    # Returns:
    #   METHOD_OK if a description block exists, METHOD_FAILED otherwise
    #<-END-FUNCTION-DESCRIPTION-BLOCK->

    #Get function type - this allows us to handle either function name
entered as text
    #or the function name entered as a function pointer (ie myfunc and not
"myfunc")
    if(is.null(attributes(function_name)))
    {
        localText<-lapply(attributes(get(function_name)), function(x)
return(gsub("\t","",x)))$source
    }else
    {
        localText<-lapply(attributes(function_name), function(x)
return(gsub("\t","",x)))$source
    }
    descSP<-which(unlist(lapply(localText, function(x){if(
length(grep(start_flag, x))==0 ){return(FALSE)}else{return(TRUE)}} )))
    descEP<-which(unlist(lapply(localText, function(x){if(
length(grep(end_flag, x))==0 ){return(FALSE)}else{return(TRUE)}} )))
    if(length(descSP)==0 | length(descEP)==0)
    {
        cat(paste("Error - function ", function_name," has no function
description included.\r\n",sep=""))
        return(invisible(METHOD_FAILED))
    }else
    {
        if(as.character(match.call())[2]=="extractFunctionDefinition"){
            ##Handle exceptional case where function is describing itself:
            descSP<-descSP[2]+1
            descEP<-descEP[3]-1
        }else{
            if(length(descSP)>1){descSP<-descSP[2]+1}else{descSP<-descSP+1}
            if(length(descEP)>1){descEP<-descEP[2]-1}else{descEP<-descEP-1}
        }
    }

    #Extract function description:
    desc<-localText[descSP:descEP]
    cat(paste(desc, collapse="\r\n"),"\r\n")

    return(invisible(METHOD_OK))
}
--------------------------------------------------------------END
FUNCTION--------------------------------------------------------------------

--------------------------------------------------------------START DEMO
CODE------------------------------------------------------------
Example Function:
flyingPigs<-function(input1, input2)
{
    #<-BEGIN-FUNCTION-DESCRIPTION-BLOCK->
    # Demo function demonstrating how to use extractFunctionDefinition()
    #
    # Declared In:
    #   <some_file.R>
    #
    # Args:
    #   input1: anything really, just to prove a point
    #   input2: just to demo how I document my input
    #
    # Returns:
    #   I always return a list list(EXIT_STATUS,<anything else>)
    #<-END-FUNCTION-DESCRIPTION-BLOCK->
    return(list(0,input1, input2))
}

extractFunctionDefinition(flyingPigs)
extractFunctionDefinition("flyingPigs")
--------------------------------------------------------------END DEMO
CODE-------------------------------------------------------------

To the rest of the R community: I realise that this is not "how things
should be done" - by the time I'd
realised that I should be writing a package I'd already created a whole slew
of tools! That'll teach me
not to read the manual.

Cormac Long.

	[[alternative HTML version deleted]]

