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

Already on GitHub? Sign in to your account

Unwanted quotation marks around aliases with commas #40

Closed
joey711 opened this Issue Sep 13, 2011 · 8 comments

Comments

Projects
None yet
2 participants

joey711 commented Sep 13, 2011

This affects especially S4 method documentation, which has an alias naming convention that builds on the generic using no-space commas as delimiter to indicate the signature, and ending with "-method" without the quotes. (http://cran.r-project.org/doc/manuals/R-exts.html#Documenting-S4-classes-and-methods)

The quotes are probably necessary during internal text-handling, but need to be removed from the final \alias{ } tag in the Rd file.

The following example S4 extension of the "show" method illustrates the problem:

' @name show

' @Aliases show show,helloworld-method

' @doctype methods

' @rdname show-methods

' @export

setMethod("show", "helloworld", function(object){
cat("Hello World!")
cat("\n")
})

Is translated by the latest version of roxygen2 to the following Rd file:

\docType{methods}
\name{show}
\alias{"show,helloworld-method"}
\alias{show}
\title{Show the helloworld class to standard output.}
\arguments{
\item{object}{A \code{helloworld} object.}
}

I have also created an example package and put on github: ( https://github.com/joey711/testpkg ) . It builds and loads fine, but throws the following errors during because the S4 methods appear undocumented (even though they are):

  • checking for missing documentation entries ... WARNING
    Undocumented S4 methods:
    generic 'helloworld' and siglist 'array'
    generic 'helloworld' and siglist 'character'
    generic 'helloworld' and siglist 'function'
    generic 'helloworld' and siglist 'helloworld'
    generic 'helloworld' and siglist 'integer'
    generic 'helloworld' and siglist 'list'
    generic 'helloworld' and siglist 'logical'
    generic 'helloworld' and siglist 'matrix'
    generic 'helloworld' and siglist 'numeric'
    generic 'print' and siglist 'helloworld'
    generic 'show' and siglist 'helloworld'
    All user-level objects in a package (including S4 classes and methods)
    should have documentation entries.
Collaborator

hadley commented Sep 13, 2011

This is the same as #29, right?

joey711 commented Sep 13, 2011

Yes, it does look like the same. I should have noticed, sorry. Does yihui's fix (yihui/roxygen2@153936f) solve the issue?

joey711 commented Sep 13, 2011

I just tried out yihui's commit. It seems to work, but I think that was an earlier clone of klutometis-master, getting an older error from generic<- without quotes in namespace. I'm going to clone klutometis add yihui's fix and see if that fixes all my problems.

Collaborator

hadley commented Sep 13, 2011

I think it should, but I haven't had a chance to do any roxygen2 development lately, hence the pull request back log :/

joey711 commented Sep 13, 2011

I'm new to github. Should this issue be closed since it is basically a duplicate? Or is it just that much more satisfying when the bug gets fixed and committed?

Collaborator

hadley commented Sep 13, 2011

Since it's a duplicate, I'll close it. I would be helpful if you'd add a minimal S4 example to the other bug report so I can check that it works for your case.

@hadley hadley closed this Sep 13, 2011

joey711 commented Sep 13, 2011

I'm not sure what the minimum should be for documenting new methods for a generic. I would be glad to know for sure what is redundant in the example below. This issue appears to affect methods extended from base generics as well (e.g. "show", "print", etc). For a (relatively) minimalist full package example that you could roxygenize, try:

https://github.com/joey711/testpkg

In principle, just including
#' @rdname helloworld-methods
above the method could be enough for a default case, since the other tags I've included below are determined by the generic or the method's signature. Or even better, creating default documentation for undocumented methods if their generic is already documented.

##############################################################
#' helloworld-ify the argument.
#'
#' @Param x The argument. Typically a character vector.
#'
#' @return A helloworld-ified argument. Oh, you'll see.
#'
#' @export
#'
#' @name helloworld
#' @Aliases helloworld
#' @doctype methods
#' @rdname helloworld-methods
#'
#' @examples
#' helloworld("thisismystring")
setGeneric("helloworld", function(x, ...){
cat("Hello World!")
cat("\n")
standardGeneric("helloworld")
})
##############################################################
#' @name helloworld
#' @Aliases helloworld,character-method
#' @doctype methods
#' @rdname helloworld-methods
setMethod("helloworld", "character", function(x){
cat(class(x), fill=TRUE)
})
##############################################################

joey711 commented Sep 13, 2011

Correction: I think a "minimal" example would not included the @name or @doctype tags above the method. I've been trying the correction on my own roxygen2 fork with just the @Aliases and @rdname tag above each method, and this seems to be working.

E.g.

##############################################################
#' helloworld-ify the argument.
#'
#' @Param x The argument. Typically a character vector.
#'
#' @return A helloworld-ified argument. Oh, you'll see.
#'
#' @export
#' @doctype methods
#' @rdname helloworld-methods
#'
#' @examples
#' helloworld("thisismystring")
setGeneric("helloworld", function(x, ...){
cat("Hello World!")
cat("\n")
standardGeneric("helloworld")
})
##############
#' @Aliases helloworld,character-method
#' @rdname helloworld-methods
setMethod("helloworld", "character", function(x){
cat(class(x), fill=TRUE)
})

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment