[Bioc-devel] Proper way of documenting a BiocGenerics generics with extended prototypes

[Christian Arnold]

Hi all,

I am currently producing the documentation for a new hopefully 
soon-to-be-submitted Bioconductor package and I am facing some 
difficulties with R CMD check.
In summary: I want to dispatch the existing generic for "counts" to make 
it usable with my object of type SNPhood as well.

The original prototype from BiocGenerics:

standardGeneric for "counts" defined from package "BiocGenerics"

function (object, ...)



I am calling, as you can see, an internal function for this. Currently, 
because of its original prototype, I use:

setMethod("counts", "SNPhood", function(object, ...) {.getCounts(object, ...)})



However, in my case, I want to use an extended prototype to specify 
which counts exactly should be extracted.

.getCounts <- function(SNPhood.o, type, readGroup = NULL, dataset = NULL, ...)



Everything works, but I want to document the additional arguments 
properly. However, with roxygen 2, I am not sure how to achieve that 
without producing warnings.

I am using:

#' @usage counts (object, type, readGroup, dataset)

#' @template object

#' @param type bla

#' @template readGroup

#' @template dataset


This produces:

* checking for code/documentation mismatches ... WARNING
Codoc mismatches from documentation object 'counts,SNPhood-method':
counts
   Code: function(object, ...)
   Docs: function(object, type, readGroup, dataset)
   Argument names in code not in docs:
     ...
   Argument names in docs not in code:
     type readGroup dataset
   Mismatches in argument names:
     Position: 2 Code: ... Docs: type



So, what is the recommended way here? I could write an own "new" counts 
function, but I thought if a generics already exists, I should use it 
because this is exactly what my function does also...


Thanks,
Christian

-- 
—————————————————————————
Christian Arnold, PhD
Staff Bioinformatician

SCB Unit - Computational Biology
Joint appointment Genome Biology
Joint appointment European Bioinformatics Institute (EMBL-EBI)

European Molecular Biology Laboratory (EMBL)
Meyerhofstrasse 1; 69117, Heidelberg, Germany

Email: christian.arnold at embl.de
Phone: +49(0)6221-387-8472
Web: http://www.zaugg.embl.de/