What I have read
I have read this SO question and related answers but I am still a bit at loss of how to document a defunct function properly in my package.
What I have tried
I replaced the code of my defunctfucntion by a call of .Defunct("<pointer to a function to be used instead>", "<my package name>")
I deleted the .Rd file containing the old documentation of my function
I created a mypackage-defunct.Rd file with an alias pointing to my now defunct function name
In mypackage-defunct.Rd I created an \usage entry for my old function and replaced the function arguments by \dots (as I do not see the need to keep track about the old arguments. I followed a bit what is done in base-defunct)
What I have got
When running RCMD CHECK I get the following WARNING:
checking Rd \usage sections ... WARNING
Undocumented arguments in documentation object 'mypackage-defunct'
'...'
Functions with \usage entries need to have the appropriate \alias
entries, and all their arguments documented.
The \usage entries must correspond to syntactically valid R code.
See chapter 'Writing R documentation files' in the 'Writing R
Extensions' manual.
What I would like to have
How do i get rid of the warning? Do I need to document arguments from defunct functions? Bonus question: What is the recommended way for a defunct function. Should I remove all arguments and replace them by ...? Looking at base-defunct, I see a mix of functions with proper argument names, . and ...arguments and empty argument lists. What is the "correct" way?
Related
I am using the devtools package to check if a package I am developing is ready for submission to CRAN.
Using Roxygen2 through devtools, I documented a small number of functions with #'#export, in order for them to be available when the package I am developing is loaded.
However, when I run devtools::check(), it seems I need to document the functions that are NOT exported, i.e. those that may be called by a function which is exported, but which are not available nor needed by whoever uses the package. Here is an example from the output of devtools::check():
checking Rd \usage sections ... WARNING
Undocumented arguments in documentation object 'calculate_agreement'
‘a_assign_star’ ‘a_assign’
Do I need to document those arguments although the function is not exported?
I believe the problem here (based on past experience) is that you are probably using Roxygen comment delimiters #' in the preamble to the function. This (I'm pretty sure) triggers the creation of a .Rd file (and the need to document parameters), whether or not you have an #export directive or not. My solution in this case was to use regular # commenting rather than #'.
Based on this answer it's possible that an explicit #keywords internal directive would also work (but I haven't tried it).
I have a package of functions; one function has 22 parameters (including ...). I've recently moved a parameter from being a ... option to being a full parameter, and noticed that even though it's described in the logical order in the function parameters list, and in the same order in the roxygen2 #params items list, when I document() , the new item is below the ... item at the bottom, and is itself followed by another param which I've got in the logical place too.
Example: Script looks like this:
#' #param ParameterA does something
#' #param ParameterB does something else
#' #param ... optional extras
foo <- function(ParameterA, ParameterB, ...)
Rd & help file look like this:
Arguments
Parameter A does something
... optional extras
Parameter B does something else
I know this is petty but does anyone know how to fix this? I deleted the .Rd file and redocument()ed to no avail.
Imgur album (3 pics) of screenshots here: http://imgur.com/a/pUX4m
Edit: more digging: I ran build & reload, check, and saw:
Documented arguments not in \usage in documentation object 'gbm.auto':‘tc’ ‘mapshape’.
Functions with \usage entries need to have the appropriate \alias entries, and all their arguments documented.
The \usage entries must correspond to syntactically valid R code.
Last paragraph before "RC" here says #usage no longer required since v3 of roxygen2 generates this automatically. But this isn't working for me any more, despite having worked in the past.
Found the culprit: another script was in the R folder with the same function within it (essentially a draft/fork of the main function with something I'm trying to change it to). (I assume that) document() was writing the Rd file for gbm.auto from gbm.auto.R then overwriting the Rd file from gbm.auto_binonly.R, deleting all the changes. Sorry folks
I wrote a method for a generic S4 function in R. The name of the generic function is extract. The class the method refers to has a hyphen in it, as in Zelig-tobit models. I'd like to write a documentation entry for the method as follows in the usage section of the respective .Rd file:
\S4method{extract}{Zelig-tobit}(model, ...)
If I do that, R CMD check --as-cran returns an error message:
* checking Rd \usage sections ... WARNING
Bad \usage lines found in documentation object 'extract':
<unescaped bksl>S4method{extract}{Zelig-tobit}(model, ...)
How do I correctly escape the hyphen?
I am currently checking my package. R CMD check gives me the following warning:
* checking for missing documentation entries ... WARNING Undocumented code objects:
followed by a list of functions.
The problem seems to be that I have 3 lists containing functions. These, however, are just small functions that exist only because I tried to modularise my code as far as possible. I would like (and have seen that previously in other packages) to just give the function list + documentation without having to provide a documentation for every single tiny function bit.
Is there a way to do this?
The mistake was that within the function list I had
funclist <- list(function1 <- function1(){})
This lead to function1 being sourced upon sourcing funclist. However, when one writes
funclist <- list(function1 = function1(){})
function1 is not sourced and can be addressed via funclist$function1() then.
In an earlier post, I asked about declaring such functions in R packages and making them work. Having succeeded, I'm now trying to document one such function.
I created an Rd file with the function's name as a title, but when running the CHECK, I get the following warning:
* checking for missing documentation entries ... WARNING
Undocumented code objects:
'%IN%'
I tried several names such as %IN%.Rd or '%IN%'.Rd, to no avail. Any hints on how to make this work?
The goto guide would definitely be section 2.1.1 "Documenting functions"[1] of the "Writing R Extensions" manual. As #joran pointed out in a comment the important part maybe the use of an \alias. According to the "Writing R extensions" manual the %s need to be escaped at least in \alias and in the text. About \name it states: " [name should not contain] ‘!’ ‘|’ nor ‘#’, and to avoid possible problems with the HTML help system it should not contain ‘/’ nor a space. (LaTeX special characters are allowed, but may not be collated correctly in the index.)"[2] and about \alias: " Percent and left brace need to be escaped by a backslash."[3]