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

Hi Jim, Kasper, and Herv?,

thanks a lot for the quick answer. For some reason, I was under the
impression that I have to use exactly the original prototype from the
generics, but I didn't fully realize I can extend this arbitrarily as
long as the original arguments - object and ... in this case, are among
the extended list.

It works now, perfect, no complaints.

*
**A related question that I have is the following, maybe someone can
share with me his or her thoughts: *

In addition to counts (for which a generics already exists), users can
extract "enrichment" instead of counts out of my object. Because there
is a generics for counts, I thought it makes conceptually sense to also
have a generics for enrichment then, because "enrichment" may also be
something that other packages may use as a general terminology in a
genomic context. So currently, I am creating one in an identical fashion
to counts.

Similarly, I defined one for "parameters" to extract parameters out of
the object that were defined previously in the main function that
creates the object.

For both "enrichment" and "parameters", I could of course also regular
functions, but I was wondering which of the two approaches I should
take. Any thoughts?

Thanks a lot, very much appreciated!
Christian



On 20.09.2015 21:09, Jim Hester wrote:

Christian,

You need to use your extended prototype in the function definition
within your `setMethod()` call.  In particular you do _not_ need to
write an explicit `@usage` directive.

See
https://github.com/jimhester/examplePrototype/blob/master/R/package.R
for an example package without any NOTEs for this situation.

Jim

On Sun, Sep 20, 2015 at 1:23 PM, Christian Arnold
<christian.arnold at embl.de <mailto:christian.arnold at embl.de>> 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

     --
     ?????????????????????????
     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 <mailto:christian.arnold at embl.de>
     Phone: +49(0)6221-387-8472 <tel:%2B49%280%296221-387-8472>
     Web: http://www.zaugg.embl.de/