Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

roxygen2 fails to generate method documentation #261

Closed
yxomo opened this issue Jun 27, 2014 · 1 comment
Closed

roxygen2 fails to generate method documentation #261

yxomo opened this issue Jun 27, 2014 · 1 comment

Comments

@yxomo
Copy link

@yxomo yxomo commented Jun 27, 2014

roxygen2 fails to generate documentation for a simple S4 method with only one parameter. I am giving example code with class A and method B below:

#' A Class
#'
#' Example class.
#'
#' @name A-class
#' @rdname A-class
#' @exportClass A
setClass("A", representation(), prototype = prototype())

setGeneric("B", function(.Object) standardGeneric("B"))

#' B-methods
#'
#' Example method on class A.
#'
#' @return The given object, invisibly.
#'
#' @docType methods
#' @rdname B-methods
#' @aliases B,A-method
#' @export
setMethod("B", "A",
        function(.Object) {
            return(invisible(.Object))
        }
)
@Geoff99
Copy link
Contributor

@Geoff99 Geoff99 commented Aug 9, 2014

Hi
I think I have some insight into which line of code generates this issue - but I don't know enough to have a suggested fix yet.
I posted details on the devtools group (since that is the route by which I began using roxygen2) at
https://groups.google.com/forum/#!topic/rdevtools/2TMDbDcPNA8
Importantly I subsequently realised part of my post was not correct and added a correction as a reply to that message.
I think the problem lies within roxygen2::get_rd see the devtools post or an extract below for why.
Hope this is helpful.
Geoff

Summary of where the problem emerges

inherit_from calls get_rd(generic, package)

get_rd <- function (topic, package = NULL) 
{
    help_call <- substitute(help(t, p), list(t = topic, p = package))
    top <- eval(help_call)
    if (length(top) == 0) 
        return(NULL)
    internal_f("utils", ".getHelpFile")(top)
}

get_rd includes a line

top <- eval(help_call)

That is where the problem arises if the .Rd file for the generic does not already exist. An error is raised, and eventually devtools::document() falls over.

If the help file for the generic is found, eval returns something which makes the rest of the code happy.

Geoff99 added a commit to Geoff99/devtools that referenced this issue Aug 12, 2014
… to date

I have experienced a couple of related issues using the devtools /
roxygen2 combination to develop and document a package.  Both issues
relate to inheritance, and the file collation order for the package
(which roxygen2 very nicely generates from the @include tags in the
roxygen comments in my R code).  I am using devtools 1.5.0.99 and
roxygen2 4.0.1

For details of the issues see :
1) issue 261 , devtools::load_all not happy :
r-lib/roxygen2#261
https://groups.google.com/forum/#!topic/rdevtools/N3wy684ccnA
https://groups.google.com/forum/#!topic/rdevtools/2TMDbDcPNA8
and
2) issue related to order of (inherited) parameters in documentation
from roxygen2
https://groups.google.com/forum/#!topic/rdevtools/KBd7X8UbqPg

These issues would be solved if :
1) devtools::load_all updated the Collate field in the description file
before attempting to load and evaluate the R code in the package
and
2) roxygen2::roxygenise read in and parsed the roxygen comment blocks
from R files in the order of the Collate sequence instead of from R
files in alphabetical filename sequence.

I have tried some 'proof of concept' tweaks to devtools::loadall and
roxygen2::roxygenise to trial this, and they do solve my immediate
problem.

My solutions are not as elegant and concise as the master devtools and
roxygen code (which is awesome!), and have not been tested in other 'use
cases', nor for efficiency, nor for other platforms (I am on Windows 7).
But perhaps they will be useful small contribution as a rough starting
point for other more experienced coders.

Regards

Geoff Lee
Geoff99 added a commit to Geoff99/roxygen that referenced this issue Aug 12, 2014
Hi

I have experienced a couple of related issues using the devtools /
roxygen2 combination to develop and document a package.  Both issues
relate to inheritance, and the file collation order for the package
(which roxygen2 very nicely generates from the @include tags in the
roxygen comments in my R code).  I am using devtools 1.5.0.99 and
roxygen2 4.0.1

For details of the issues see :
1) issue 261 , devtools::load_all not happy :
r-lib#261
https://groups.google.com/forum/#!topic/rdevtools/N3wy684ccnA
https://groups.google.com/forum/#!topic/rdevtools/2TMDbDcPNA8
and
2) issue related to order of (inherited) parameters in documentation
from roxygen2
https://groups.google.com/forum/#!topic/rdevtools/KBd7X8UbqPg

These issues would be solved if :
1) devtools::load_all updated the Collate field in the description file
before attempting to load and evaluate the R code in the package
and
2) roxygen2::roxygenise read in and parsed the roxygen comment blocks
from R files in the order of the Collate sequence instead of from R
files in alphabetical filename sequence.

I have tried some 'proof of concept' tweaks to devtools::loadall and
roxygen2::roxygenise to trial this, and they do solve my immediate
problem.

My solutions are not as elegant and concise as the master devtools and
roxygen code (which is awesome!), and have not been tested in other 'use
cases', nor for efficiency, nor for other platforms (I am on Windows 7).
But perhaps they will be useful small contribution as a rough starting
point for other more experienced coders.

Regards

Geoff Lee
@hadley hadley closed this in faef9a6 Aug 29, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants