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.
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 standard way of writing documentation with code formatting is by using \code{}.
That is, #' #param foo value passed on to \code{bar()} becomes
Arguments
foo value passed on to bar()
However, I've seen some packages (i.e. dplyr) using backticks instead of \code{} to the same effect. This is much better, since it's less clunky and allows for very nice syntax highlighting.
However, if I try that on my own package, the backticks get interpreted as... just backticks, like any other character.
The documentation for dplyr::across(), for example, starts with:
#' #description
#' `across()` makes it easy to apply the same transformation to multiple [...]
which gets compiled and displayed in the man page as:
Description
across() makes it easy to apply the same transformation to multiple [...]
But if I try something similar on my package, I get:
Description
`across()` makes it easy to apply the same transformation to multiple [...]
Weirdly, I've forked the package glue (which also manages to use backticks for code formatting) for a simple PR, and if I build the package locally, the backticks work (I get code formatting). Can't for the life of me figure out why it works there but not for my package.
So, is there some setting I need to modify to get this to work? I checked the dplyr.Rproj but found nothing relevant. I also glanced at the Doxyfile, but didn't know what it did or what I'd even be looking for there.
All credit goes to #rawr's comment to the question, just formalizing it with an answer:
The secret is in the roxygen2 documentation: just add the following to the end of the package DESCRIPTION file:
# DESCRIPTION file
# [... rest of file ...]
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.2 # actually works since 6.0.0
As that code would imply, this sets roxygen2 to interpret the commands as good ol' Markdown like we're used to using here on SO and elsewhere. This also implies all the other standard Markdown commands such as **bold** and *italics*, as well as [text](http://www.url.com), code blocks defined by ```, itemized and enumerated lists, etc. It's a huge improvement across the board.
Though be careful and take a look at the documentation, since there are a few gotchas. For instance, an empty line isn't necessary to start lists, so don't start any lines with #' 1. [...] or #' * [...] or you'll accidentally create a list!). There's also a few things which don't work yet, but they're pretty minor.
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
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
Is there some mechanism by which I can transform the comments that roxygen sees, preferably before it does the roxygen->rd conversion?
For example, suppose I have:
#' My function. Does stuff with numbers.
#'
#' This takes an input `x` and does something with it.
#' #param x a number.
myFunction <- function (x) {
}
Now, suppose I want to do some conversion of the comment before roxygen parses it, for example replacing all instances of things in backticks with \code{}. Ie:
preprocess <- function (txt) {
gsub('`([^ ]+)`', '\\\\code{\\1}', txt)
}
# cat(preprocess('Takes an input `x` and does something with it'.))
# Takes an input \code{x} and does something with it.
Can I feed preprocess into roxygen somehow so that it will run it on the doclets before (or after would work in this case) roxygen does its document generation?
I don't want to do a permanent find-replace in my .r files. As you might guess from my example, I'm aiming towards some rudimentary markdown support in my roxygen comments, and hence wish to keep my .r files as-is to preserve readability (and insert the \code{..} stuff programmatically).
Should I just write my own version of roxygenise that runs preprocess on all detected roxygen-style comments in my files, saves them temporarily somewhere, and then runs the actual roxygenise on those?
Revisiting this a couple of years later, it looks like Roxygen has a function register.preref.parsers that one can use to inject their own parsers into roxygen.
One such use of this is the promising maxygen package (markdown + roxygen = maxygen), which a very neat implementation of markdown processing of roxygen comments (albeit only to the CommonMark spec), and you can see how it is used in that package's macument function. I eagerly await "pandoc + roxygen = pandoxygen"... :)