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

[Hervé Pagès]

Hi Christian,

This has not much to do with roxygen. 'R CMD check' complains that your
"counts" method doesn't have the arguments that your man page says it
has. Your method is defined with arguments (object, ...) but the \usage
section in the man page says it has arguments (object, type, readGroup,
dataset). You would get the same warning if you were documenting an
ordinary function with the incorrect argument list in the \usage
section. So you need to change one or the other. Either you define the
method with something like

   setMethod("counts", "SNPhood",
     function(object, type, readGroup, dataset) {
       ...
     }
   )

or you put counts(object, ...) in the \usage section of your man page.

Personally I have a strong preference for the former because:
   (a) Arguments are easier to document for you and easier to discover
       for the user (s/he'll see them when s/he does
       selectMethod("counts", "SNPhood")).
   (b) Because the method does not have the ellipsis in its arguments,
       then calling the method with a mis-spelled argument is an error
       (as it should). Otherwise the mis-spelled argument is silently
       ignored which can have disastrous consequences.

Hope this helps,
H.


On 09/20/2015 10:23 AM, Christian Arnold wrote:
> 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
>

-- 
Hervé Pagès

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fredhutch.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319