when I perform check of a package in Rstudio, I get this note "Dropping empty section \value".
It happens during the checking of the Rd files.
checking Rd files ... NOTE
prepare_Rd: function.Rd:20-22: Dropping empty section \value
Did somebody encounter such an error, and do you know how to solve it???
All help is much appreciated...
This means that at least one of the fields in your Roxygen skeleton doesn't contain any value.
If, for instance, you are not providing any information about the return, either provide it:
#' #return <information>
or remove the whole #' #return line.
I just had the same problem - it was due to a bracket mismatch ('{' instead of '[') in the 'preamble' (i.e., the #' - section) of the file. You might want to check the log of the compilation (subdir package.Rcheck).
Don't know why this error occurred, but I rewrote the #return in roxygen skeleton and know I don't get this note on checking.
If somebody is experiencing this problem as well, try rewriting #return
Related
I'm new to both {box} and {roxygen2} and have never written a package - so please bear with me.
I've got a script that has a smallish function in it which I've verified works at my end. It's sited in a bespoke folder I've created, called R, inside the 'package' folder, e.g. 'Module1/R/functionscript1.R'. The script contains all the bits of {roxygen2} commenting that I think I need, including #' #export. I can't quite figure out the next stages despite reading many blogs. How do I turn this into a fully documented {box} module?
I've tried setting my working directory to the Module1 directory then using devtools::document(), which errors out telling me it can't find the package root (" Is . inside a package?"). No version of box::use() is doing anything I think it should. What am I missing?? Please explain like I'm a toddler.....
Thanks
With ‘box’, there’s no need to call devtools::document(). And in fact you can see from the error message that it doesn’t work.
Writing your documentation comment inside the module is all that’s required. When you now load the module you can display its documentation.
Let’s say your Module1/R/functionscript.R looks like this:
#' Some test function
#' #param n a number
#' #return the modified number
#' #export
modify = function (n) {
n * 2 - 1
}
Then you can load your module (note that having R in the directory name is a bit weird when working with modules, since it will become part of the module name):
box::use(./Module1/R/functionscript)
After loading the module you can use it:
functionscript$modify(5)
# [1] 9
And you can display its documentation via box::help:
box::help(functionscript$modify)
And this will display the help, e.g.:
The last R expression to be evaluated in a function will become the return value of that function. We want this function to take one argument, x, and return x without modifying it. Delete the pound sign so that x is returned without any modification. Make sure to save your script before you type submit().
There is a problem with swirl package, where the function learning section gives the problem related to boring function
I found that problem extremely fustrating you can type skip(). I found that if I saved the file: ie summerize1.R before I entered submit(); then it will work. There must be a failure somewhere between my tempfiles and the swirl updating them. i am not experienced enough to figure that one out but saving the file works. I hvae tried it on Gathering and filtering and the tydr one as well.
If you mean the problem where the submit function is not found, you can run it directly from the swirl package.
> submit()
Error in submit() : could not find function "submit"
> swirl::submit()
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'm documenting a function using roxygen2 with an #example.
The example has a string that contains a } symbol.
#' ...
#' #examples
#' \dontrun{
#' ## polyline joining the capital cities of Australian states
#' pl <- "nnseFmpzsZgalNytrXetrG}krKsaif#kivIccvzAvvqfClp~uBlymzA~ocQ}_}iCthxo#srst#"
#'
#' df_polyline <- decodepl(pl)
#' }
#' ...
When built, the documentation for the example is
Where everything after the first } is cutt off.
How do I escape the } so that it is included in the string in the example?
I've tried a backslash \{ / \\{ with no luck.
Update - 01 Sep 2016
The official response to my issue from Hadley
Fixing this is quite difficult (as far as I can it will require writing a considerably more complicated Rd parser), and it's a rare occurrence, so realistically this is never going to get high up enough on my to do list to fix it.
TLDR: longer term fix: file an issue.
You "got lucky" this built since you had just enough }'s to get past some Rd installation errors.
I even tried using #example inst/examples/ex.r and putting the code (with the \dontrun{} wrapper since it is supported there) and the same thing happens with that method since the same roxygen parsing/translating code seems to be in play there too.
SHORT TERM FIX #1: manually edit the generated Rd file to do the single \} for each of the }. To make this something you don't accidentally overwrite, generate it once, do the fix then de-roxygenize that function until there's a fix.
SHORT TERM FIX #2: for that bit of code, the string assignment can happen outside of the \dontrun{} block (which is really what's causing this). Move it out and you can continue with roxygenizing.
LONG TERM FIX: file an issue to the above URL.
I imagine this is a simple thing that I keep overlooking in the documentation, but I can't seem to figure out how to get package-level documentation to work in R. I'm not referring to function or class-specific documentation, but the documentation that you get when you type, for example, ?stats.
I've followed the general instructions I've found on the web, creating a sckeleton documentation file saved as .R. The .R file is copied with the package scripts, but the help documentation doesn't get made into a .Rd file (unless I add a function definition also named after the package).
An example of what I've tried:
#'_PACKAGE
#'MyPackage
#'
#'MyPackage description
#'
#'MyPackage details
#'#alias{MyPackage}
#'#alias{MyPackage-package}
I'm having a hard time finding good examples of how to set up general package documentation, for some reason. I've written quite a few function help files, and I know my package help file is being found by roxygen, but it's unclear why I can't generate an .Rd from it.
Answer courtesy of #slickrickulicious in the comments above:
I needed to add NULL at the end of my documentation file and include '#name MyPackage'. Doing so generated the package help file correctly.
I made my package (called pkgName) using devtools and already had a file named pkgName_package.R that was automatically generated. It contained the following lines:
#' #keywords internal
#' #aliases pkgName-package
"_PACKAGE"
After removing the first line, #keywords internal, and rebuilding, pkgName-package was a documented topic that appeared at the top of the reference manual.