Hi all, I am writing a function (fun.R), but I dont know how to code the function so that the Help Text will be shown up when one types ?fun (of course, after he loads it up). Anyone has any advice for me how to do that? Thanks, D.
On 16/09/2010 3:40 PM, Duke wrote:> Hi all, > > I am writing a function (fun.R), but I dont know how to code the > function so that the Help Text will be shown up when one types ?fun (of > course, after he loads it up). Anyone has any advice for me how to do that? > >The help text is separate from the function (unless you use the roxygen package or similar). You need to write a package so that R will find the help; instructions are in the Writing R Extensions manual. Duncan Murdoch
Hi Duncan, On 9/16/10 3:47 PM, Duncan Murdoch wrote:> On 16/09/2010 3:40 PM, Duke wrote: >> Hi all, >> >> I am writing a function (fun.R), but I dont know how to code the >> function so that the Help Text will be shown up when one types ?fun (of >> course, after he loads it up). Anyone has any advice for me how to do >> that? >> >> > > The help text is separate from the function (unless you use the > roxygen package or similar). You need to write a package so that R > will find the help; instructions are in the Writing R Extensions manual.I was expecting something simpler than writing a package, and that I can integrate it into fun.R, but thanks anyway. D.> > Duncan Murdoch >
On 17/09/2010, at 8:51 AM, Duke wrote:> Hi Duncan, > > On 9/16/10 3:47 PM, Duncan Murdoch wrote: >> On 16/09/2010 3:40 PM, Duke wrote: >>> Hi all, >>> >>> I am writing a function (fun.R), but I dont know how to code the >>> function so that the Help Text will be shown up when one types ?fun (of >>> course, after he loads it up). Anyone has any advice for me how to do >>> that? >>> >>> >> >> The help text is separate from the function (unless you use the >> roxygen package or similar). You need to write a package so that R >> will find the help; instructions are in the Writing R Extensions manual. > > I was expecting something simpler than writing a package, and that I can > integrate it into fun.R, but thanks anyway.(a) Writing a package is not all that hard. (b) It focuses the mind wondrously. (c) Using R CMD check on the package is very useful for picking the lint off the code. cheers, Rolf Turner ###################################################################### Attention:\ This e-mail message is privileged and confid...{{dropped:9}}
On 9/16/10 5:00 PM, Rolf Turner wrote:> On 17/09/2010, at 8:51 AM, Duke wrote: > >> Hi Duncan, >> >> On 9/16/10 3:47 PM, Duncan Murdoch wrote: >>> On 16/09/2010 3:40 PM, Duke wrote: >>>> Hi all, >>>> >>>> I am writing a function (fun.R), but I dont know how to code the >>>> function so that the Help Text will be shown up when one types ?fun (of >>>> course, after he loads it up). Anyone has any advice for me how to do >>>> that? >>>> >>>> >>> The help text is separate from the function (unless you use the >>> roxygen package or similar). You need to write a package so that R >>> will find the help; instructions are in the Writing R Extensions manual. >> I was expecting something simpler than writing a package, and that I can >> integrate it into fun.R, but thanks anyway. > (a) Writing a package is not all that hard.You can say so if you are fluent in R. I just started and have written only 20-30 lines of codes so far. Also, writing a package is still more complicated than writing a simple function (single file). Why R is so different from other languages (python, matlab or more basics like C/C++ etc...)? In fact I still feel very uncomfortable with R, for example, I hate when I type a function name, it shows the whole function. Honestly I feel a world of programming is a mess, and it is tough when one wants to jump from one language to another.> (b) It focuses the mind wondrously.I did try to write a simple package (followed a tutorial), but did not find what you said :). Maybe I need more practice.> (c) Using R CMD check on the package is very useful for picking the > lint off the code. >It would be great if you share your experience a little more about this. Thanks, D.> cheers, > > Rolf Turner > > ###################################################################### > Attention: > This e-mail message is privileged and confidential. If you are not the > intended recipient please delete the message and notify the sender. > Any views or opinions presented are solely those of the author. > > This e-mail has been scanned and cleared by MailMarshal > www.marshalsoftware.com > ###################################################################### >
If having the definition of the function appear when you enter the name of the function elicits a "hate" response, then perhaps you should not be using R. That characteristic of R is fundamental and unlikely to change: in R everything is an object, and the result of evaluating an expression is displayed at the command line. Other languages have different unifying principles, and may be appropriate for different tasks. Anything that can be done in R could be done in, say, C, but by the time you did so you might find yourself learning very similar lessons to the ones R assumes you know. "Duke" <duke.lists at gmx.com> wrote:> On 9/16/10 5:00 PM, Rolf Turner wrote: >> On 17/09/2010, at 8:51 AM, Duke wrote: >> >>> Hi Duncan, >>> >>> On 9/16/10 3:47 PM, Duncan Murdoch wrote: >>>> On 16/09/2010 3:40 PM, Duke wrote: >>>>> Hi all, >>>>> >>>>> I am writing a function (fun.R), but I dont know how to code the >>>>> function so that the Help Text will be shown up when one types ?fun (of >>>>> course, after he loads it up). Anyone has any advice for me how to do >>>>> that? >>>>> >>>>> >>>> The help text is separate from the function (unless you use the >>>> roxygen package or similar). You need to write a package so that R >>>> will find the help; instructions are in the Writing R Extensions manual. >>> I was expecting something simpler than writing a package, and that I can >>> integrate it into fun.R, but thanks anyway. >> (a) Writing a package is not all that hard. > >You can say so if you are fluent in R. I just started and have written >only 20-30 lines of codes so far. Also, writing a package is still more >complicated than writing a simple function (single file). Why R is so >different from other languages (python, matlab or more basics like C/C++ >etc...)? In fact I still feel very uncomfortable with R, for example, I >hate when I type a function name, it shows the whole function. > >Honestly I feel a world of programming is a mess, and it is tough when >one wants to jump from one language to another. > >> (b) It focuses the mind wondrously. > >I did try to write a simple package (followed a tutorial), but did not >find what you said :). Maybe I need more practice. > >> (c) Using R CMD check on the package is very useful for picking the >> lint off the code. >> > >It would be great if you share your experience a little more about this. > >Thanks, > >D. > >> cheers, >> >> Rolf Turner >> >> ###################################################################### >> Attention: >> This e-mail message is privileged and confidential. If you are not the >> intended recipient please delete the message and notify the sender. >> Any views or opinions presented are solely those of the author. >> >> This e-mail has been scanned and cleared by MailMarshal >> www.marshalsoftware.com >> ###################################################################### >> > >______________________________________________ >R-help at r-project.org mailing list >https://stat.ethz.ch/mailman/listinfo/r-help >PLEASE do read the posting guide http://www.R-project.org/posting-guide.html >and provide commented, minimal, self-contained, reproducible code.--------------------------------------------------------------------------- Jeff Newmiller The ..... ..... Go Live... DCN:<jdnewmil at dcn.davis.ca.us> Basics: ##.#. ##.#. Live Go... Live: OO#.. Dead: OO#.. Playing Research Engineer (Solar/Batteries O.O#. #.O#. with /Software/Embedded Controllers) .OO#. .OO#. rocks...1k --------------------------------------------------------------------------- Sent from my phone. Please excuse my brevity.
On 9/17/10 12:46 PM, Jeff Newmiller wrote:> If having the definition of the function appear when you enter the name of the function elicits a "hate" response, then perhaps you should not be using R. That characteristic of R is fundamental and unlikely to change: in R everything is an object, and the result of evaluating an expression is displayed at the command line. Other languages have different unifying principles, and may be appropriate for different tasks. >Well, *hate* or *love* is just a matter of time and / or habit, so it will not interfere with me doing anything, especially in work related. I dont mind learning anything that will serve me well. Indeed, some projects that I am currently working with involve some R packages and hence some R coding as well, so I will use R no matter if I hate it or not.> Anything that can be done in R could be done in, say, C, but by the time you did so you might find yourself learning very similar lessons to the ones R assumes you know.I have zero background on programming, so I prefer to work and learn in C/C++ if I have a chance (and time). But if I need something quick, then I will have to use something like matlab, R or python.> "Duke"<duke.lists at gmx.com> wrote: > >> On 9/16/10 5:00 PM, Rolf Turner wrote: >>> On 17/09/2010, at 8:51 AM, Duke wrote: >>> >>>> Hi Duncan, >>>> >>>> On 9/16/10 3:47 PM, Duncan Murdoch wrote: >>>>> On 16/09/2010 3:40 PM, Duke wrote: >>>>>> Hi all, >>>>>> >>>>>> I am writing a function (fun.R), but I dont know how to code the >>>>>> function so that the Help Text will be shown up when one types ?fun (of >>>>>> course, after he loads it up). Anyone has any advice for me how to do >>>>>> that? >>>>>> >>>>>> >>>>> The help text is separate from the function (unless you use the >>>>> roxygen package or similar). You need to write a package so that R >>>>> will find the help; instructions are in the Writing R Extensions manual. >>>> I was expecting something simpler than writing a package, and that I can >>>> integrate it into fun.R, but thanks anyway. >>> (a) Writing a package is not all that hard. >> You can say so if you are fluent in R. I just started and have written >> only 20-30 lines of codes so far. Also, writing a package is still more >> complicated than writing a simple function (single file). Why R is so >> different from other languages (python, matlab or more basics like C/C++ >> etc...)? In fact I still feel very uncomfortable with R, for example, I >> hate when I type a function name, it shows the whole function. >> >> Honestly I feel a world of programming is a mess, and it is tough when >> one wants to jump from one language to another. >> >>> (b) It focuses the mind wondrously. >> I did try to write a simple package (followed a tutorial), but did not >> find what you said :). Maybe I need more practice. >> >>> (c) Using R CMD check on the package is very useful for picking the >>> lint off the code. >>> >> It would be great if you share your experience a little more about this. >> >> Thanks, >> >> D. >> >>> cheers, >>> >>> Rolf Turner >>> >>> ###################################################################### >>> Attention: >>> This e-mail message is privileged and confidential. If you are not the >>> intended recipient please delete the message and notify the sender. >>> Any views or opinions presented are solely those of the author. >>> >>> This e-mail has been scanned and cleared by MailMarshal >>> www.marshalsoftware.com >>> ###################################################################### >>> >> ______________________________________________ >> R-help at r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-help >> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html >> and provide commented, minimal, self-contained, reproducible code. > --------------------------------------------------------------------------- > Jeff Newmiller The ..... ..... Go Live... > DCN:<jdnewmil at dcn.davis.ca.us> Basics: ##.#. ##.#. Live Go... > Live: OO#.. Dead: OO#.. Playing > Research Engineer (Solar/Batteries O.O#. #.O#. with > /Software/Embedded Controllers) .OO#. .OO#. rocks...1k > --------------------------------------------------------------------------- > Sent from my phone. Please excuse my brevity. >
Hi r-help-bounces at r-project.org napsal dne 17.09.2010 17:02:29:> On 9/16/10 5:00 PM, Rolf Turner wrote: > > On 17/09/2010, at 8:51 AM, Duke wrote: > > > >> Hi Duncan, > >> > >> On 9/16/10 3:47 PM, Duncan Murdoch wrote: > >>> On 16/09/2010 3:40 PM, Duke wrote: > >>>> Hi all, > >>>> > >>>> I am writing a function (fun.R), but I dont know how to code the > >>>> function so that the Help Text will be shown up when one types ?fun(of> >>>> course, after he loads it up). Anyone has any advice for me how todo> >>>> that? > >>>> > >>>> > >>> The help text is separate from the function (unless you use the > >>> roxygen package or similar). You need to write a package so that R > >>> will find the help; instructions are in the Writing R Extensionsmanual.> >> I was expecting something simpler than writing a package, and that Ican> >> integrate it into fun.R, but thanks anyway. > > (a) Writing a package is not all that hard. > > You can say so if you are fluent in R. I just started and have written > only 20-30 lines of codes so far. Also, writing a package is still more > complicated than writing a simple function (single file). Why R is so > different from other languages (python, matlab or more basics like C/C++> etc...)? In fact I still feel very uncomfortable with R, for example, I > hate when I type a function name, it shows the whole function. > > Honestly I feel a world of programming is a mess, and it is tough when > one wants to jump from one language to another.If you just want your function to start each time you start R put it in a file like myfun1.r and source this file each time you start R. Modify file Rprofile.site in etc directory to do source during start up or put file .Rprofile into your working directory. Keeping several functions in a package is an option, however I must agree that for those who do not do it regularly it is a bit cumbersome. Regards Petr> > > (b) It focuses the mind wondrously. > > I did try to write a simple package (followed a tutorial), but did not > find what you said :). Maybe I need more practice. > > > (c) Using R CMD check on the package is very useful for picking the > > lint off the code. > > > > It would be great if you share your experience a little more about this. > > Thanks, > > D. > > > cheers, > > > > Rolf Turner > > > > ###################################################################### > > Attention: > > This e-mail message is privileged and confidential. If you are not the > > intended recipient please delete the message and notify the sender. > > Any views or opinions presented are solely those of the author. > > > > This e-mail has been scanned and cleared by MailMarshal > > www.marshalsoftware.com > > ###################################################################### > > > > ______________________________________________ > R-help at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guidehttp://www.R-project.org/posting-guide.html> and provide commented, minimal, self-contained, reproducible code.
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]]