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

[Christian Arnold]

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/
>
>     _______________________________________________
>     Bioc-devel at r-project.org <mailto:Bioc-devel at r-project.org> mailing
>     list
>     https://stat.ethz.ch/mailman/listinfo/bioc-devel
>
>

-- 
—————————————————————————
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/


	[[alternative HTML version deleted]]