yihui / rd2roxygen

Convert Rd to roxygen documentation

Rd2roxygen

Convert Rd to roxygen documentation. For more information, see https://yihui.org/Rd2roxygen.

rd2roxygen's Issues

Conversion fails if function name contains a regex metacharacter

Rd2roxygen() throws the error below if the function name contains a regex metacharacter (e.g. "[" for a subset method).

##------ Sun Mar 10 10:10:18 2024 ------##
parsed: subset.xts.Rd
looking for the object '[.xts' in:
Error in grep(sprintf(pattern, gsub("\\.", "\\\\.", fname)), (r.Rd = readLines(r,  : 
  invalid regular expression '^[[:space:]]*(`|"|'|)([\.xts)(\1)[[:space:]]*(<-|=)', reason 'Missing ')''
In addition: Warning message:
In grep(sprintf(pattern, gsub("\\.", "\\\\.", fname)), (r.Rd = readLines(r,  :
  TRE pattern compilation error 'Missing ')''

You already escape any "." in the function name. Here's a patch that escapes all the regular expression metacharacters. This worked for me. Let me know if you'd like a PR.

diff --git a/R/rd2roxygen.R b/R/rd2roxygen.R
index 40ba00f..f5ab07d 100644
--- a/R/rd2roxygen.R
+++ b/R/rd2roxygen.R
@@ -207,7 +207,7 @@ Rd2roxygen = function(pkg, nomatch, usage = FALSE) {
     for (i in tryf) {
       r = file.path(R.dir, i)
       idx = grep(sprintf('^[[:space:]]*(`|"|\'|)(%s)(\\1)[[:space:]]*(<-|=)',
-                          gsub('\\.', '\\\\.', fname)),
+                          gsub('([][{}()+*^$|?.])', '\\\\\\1', fname)),
                   (r.Rd = readLines(r, warn = FALSE)))
       message('  ', i, ': ', appendLF = FALSE)
       message(ifelse(length(idx), paste('line', idx), 'not found'))

包的位置位于磁盘根目录时出错

Windows系统下，当包的位置位于磁盘根目录时，比如D:\R2SWF，转换会出错。

Don't wrap in Rd2roxygen()

roxygen2 doesn't wrap anymore either. If the .Rd files are correct, so should be the generated roxygen comments.

I can create a pull request if you're interested, but this probably should be discussed first.

@ in the text are not always replaced

I noticed emails get parsed well (double @@), but if other @ signs appear, they are not "escaped" with another @ sign, which causes an error for roxygenize(). If need be, I can provide a small example.

@export functions

I see from package?Rd2roxygen that the documentation says

currently '@export' is not included in the comments

It would be great to be able to parse a NAMESPACE file to update the @exports, @method, @S3methods, etc

Following a question that I asked on Stack Overflow, I at least got as far as replacing ##' @return something with ##' @exports\n##'@ return something using code available as a gist. I doubt that the code is mature enough to insert into the package at present, but perhaps it is a start.

Rd2roxygen::Rd2roxygen() adds trailing whitespaces

Hi @yihui,
The function adds trailing whitespaces to roxygenized documentation. Those whitespaces should be removed. It may seem like a minor issue but this will start to become a problem when scaling up.
Thanks,
Marcel

Output to maxygen?

Can this be updated to accommodate output to maxygen, which will hopefully be a core part of roxygen soon (see r-lib/roxygen2#365)?

conflict with roxygen2 3.0?

It appears I can install from source, but installing from CRAN with the development version of roxygen2 (3.0) gives the following error:

> install.packages("Rd2roxygen")
Installing package into '/home/cboettig/R/x86_64-pc-linux-gnu-library/3.0'
(as 'lib' is unspecified)
trying URL 'http://cran.r-project.org/src/contrib/Rd2roxygen_1.3.tar.gz'
Content type 'application/x-gzip' length 161178 bytes (157 Kb)
opened URL
==================================================
downloaded 157 Kb

* installing *source* package 'Rd2roxygen' ...
** package 'Rd2roxygen' successfully unpacked and MD5 sums checked
** R
** inst
** preparing package for lazy loading
Error : object 'collate_roclet' is not exported by 'namespace:roxygen2'
ERROR: lazy loading failed for package 'Rd2roxygen'
* removing '/home/cboettig/R/x86_64-pc-linux-gnu-library/3.0/Rd2roxygen'
* restoring previous '/home/cboettig/R/x86_64-pc-linux-gnu-library/3.0/Rd2roxygen'

The downloaded source packages are in
    '/tmp/Rtmp4ei8Ni/downloaded_packages'
Warning message:
In install.packages("Rd2roxygen") :
  installation of package 'Rd2roxygen' had non-zero exit status

\href{}{} drops brackets

I just started using this and noticed that tags of the form \href{URL}{TEXT} get converted to \href{URLTEXT} (brackets dropped). I'm not sure where this is happening in the code, though, so I don't know how to send a patch.

Fails to parse certain tags

Trying to parse:

\title{Convert \R{} objects to/from JSON}

turns into

$title
[1] "Convert  objects to/from JSON"

Should keep formatting in \preformatted

Right now formatting is lost.

Encoding

In my old xxx.Rd I have

\author{\enc{Göran Broström}{George Bridgewater}}

where the second name is an English translation of my Swedish name. This becomes

#' @author \enc{Göran BroströmGeorge Bridgewater}

after Rd2roxygen, and

\author{
\enc{Göran BroströmGeorge Bridgewater}
}

after devtools::document()

Not good. What can we do? Is the use of \enc{}{} obsolete?

Best, Göran/George/Yuri/Goran

Comments in Rd files?

Hi, thanks for such a great package. I used it to convert some .Rd files. One problem I noted was that comments (starting with %%) in my .Rd file were just copied, as-is, to the roxygen code. This casused a problem as I had a comment in my examples section:

\examples{
stopifnot(isTRUE(all.equal.numeric(
  histbi.ab(c(0), c(-2, -2, 0, 0, 1, 1,1, 1.8,2), tmax=2, nbins=4),
  c(2,0,2,5),
  check.attributes=FALSE)))
stopifnot(identical(TRUE, all.equal.numeric(
  hist.ab(c(0), c(-2, -2, 0, 0, 1, 1,1, 1.8,  2), tmax=2, nbins=4),
  c(2,0,3,4),
  check.attributes=FALSE)))

test.hist.ab()


%% Following examples are not run since they either take a long time
%% or require an "s" structure.
\dontrun{
test.histograms.versus.r()
test.count.hist.nab()
test.count.hist.nab(s)
test.count.hist2.nab(s)
}
}

Then when R CHECK was running, it hit %% and complained. My solution for now is to remove the comment, but just thought I'd let you know.

Including a `NULL` at end of a package file

When converting a package's Rd file to roxygen2 syntax, would it be desirable to include a NULL at the end. The current version on CRAN (version 1.1 released July 13, 2012) doesn't appear to for me.

It took me a while to understand the issue and find the appropriate correction ("Like for data sets, there isn't a object that we can document directly so document NULL and use @name to say what we're actually documenting" at https://github.com/hadley/devtools/wiki/docs-function/184a50edeeb0d5a6aea14b369a786badb1abc97d).

To be a little more specific, the output would have one more line that's NULL when something like this is run:

(info = parse_file( "man/plyr.Rd"))
cat(create_roxygen(info), sep = "\n")

(I got that syntax from the 2nd example of the Rd2oxygen vignette.

Rd2roxygen mangles \itemize and \describe

again on the 141 pages of PerformanceAnalytics documentation...

Rd2roxygen mangles \itemize and \describe

\itemize{ 
     \item return depth of drawdown
     \item from starting period 
     \item to ending period \item length length in periods 
}

becomes:

#' \itemize{ \itemreturn depth of drawdown
#' \itemfrom starting period   \itemto ending 
#' period \itemlength length in periods }

losing the wrapping is annoying, but manageable.

Mangling the \item tags to concatenate \item with the first argument is just wrong.

The same thing happens for \describe

Regards,

Brian

Rd2roxygen doesn't preserve escaped % signs

I finally came back to the 141 pages of documentation for Performanceanalytics to complete converting it to roxygen2.

Rd2roxygen fails to preserve escaped % signs from the original Rd files.

All % escaped percentage signs end up in roxygen comments unescaped. This causes quite a lot of trouble to find them all and re-escape them by hand.

remember to update the vignette

since it is using roxygen2, the vignette should be updated accordingly

remove the redundant title in description

and remove the period in the title

use roxygen2

roxygen2 is way better than roxygen

Incorrect conversion of an existing package: using @alias instead of @name

For the futile.logger package, a few manual changes were necessary. See the result of the conversion vs. the manual changes.

"\R" is not recognized as a zero-arg macro

reconstruct() tests for "special" macros with tag(rd) == toupper(tag(rd)), which gives a false-positive for "\\R". This causes reconstruct() to omit the "\\R" from the text in the Rd file and so it doesn't show up in the roxygen comments after conversion.

Here's a simple example. Put the text below in a file named simple.Rd.

\name{simple}
\alias{simple}
\title{simple}
\description{simple}
\usage{simple(...)}
\arguments{
  \item{\dots}{
    ...
  }
}
\details{
  \cr 
  This is an \R function that isn't in \pkg{base}.\cr
  There's a tab character at the end of this sentence.\tab
  This is some \code{code}.
}

Then run the code below. Note the output has "This is an function..." when it should be "This is an \\R function..."

rd <- tools::parse_Rd("simple.Rd")
names(rd) <- gsub("\\\\", "", sapply(rd, Rd2roxygen:::tag))
Rd2roxygen:::reconstruct(Rd2roxygen:::untag(rd$details))
## [1] "\n  \\cr\n  This is an  function that isn't in \\pkg{base}.\\cr\n  There's a tab character at the end of this sentence.\\tab\n  This is some \\code{code}.\n"

This patch gets partway there... it doesn't omit the "\\R" but it adds curly braces and introduces another bug. I don't know enough about what's going on here to come up with a correct solution.

I also added '\\dots' and '\\ldots' to the singles vector because they're listed as zero-arg macros in tools:::as.character.Rd source, but I'm not sure whether or not that's the correct thing to do here either.

diff --git a/R/utils.R b/R/utils.R
index d46e5ce..4af255a 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -22,8 +22,8 @@ reconstruct = function(rd) {
                      '}', sep = "", collapse = ""))
       } else if (length(rd) == 0) return(tag(rd))
     }
-    special = tag(rd) == toupper(tag(rd))
-    singles = tag(rd) %in% c('\\tab', '\\cr')
+    special = tag(rd) == toupper(tag(rd)) && tag(rd) != '\\R'
+    singles = tag(rd) %in% c('\\tab', '\\cr', '\\dots', '\\ldots', '\\R')
     prefix = ifelse(special, "",
                      paste(tag(rd), ifelse(singles, "", "{"), sep = ""))
     suffix = ifelse(special, "", ifelse(singles, "", "}"))

should be able to reformat \method{}{}

i.e. S3 method

fails to parse_file if keyword empty

parse_file() breaks on the following Rd file:

\name{dumb}
\alias{dumb}
\keyword{}

with error

Error in FUN(X[[i]], ...) : subscript out of bounds

Fixed by putting some string in keyword or dropping this line

Not parsing multiple sections in Rd's

Consider this Rd as per this stack overflow question https://stackoverflow.com/questions/5275578/arbitrary-sections-in-roxygen-docs

\name{llama}
\alias{llama}
\title{Llama llama llama}
\usage{
  llama(notused)
}
\arguments{
  \item{notused}{A parameter that isn't used at all!}
}
\description{
  More about llamas
}
\section{Llamas}{
  Are they ungulates?
}

\section{Not llamas}{
  This section is not about llamas.  It is not very
  interesting.
}

Only the first section is parsed:

Rd2roxygen::parse_file("tmp.Rd")
#> $title
#> [1] "Llama llama llama"
#> 
#> $usage
#> [1] "\n  llama(notused)\n"
#> 
#> $desc
#> [1] "\n    More about llamas\n    "
#> 
#> $section
#> [1] "Llamas: \n    Are they ungulates?\n    "
#> 
#> $author
#> character(0)
#> 
#> $name
#> [1] "llama"
#> 
#> $keywords
#> list()
#> 
#> $params
#> [1] "notused A parameter that isn't used at all!"