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

[Kasper Daniel Hansen]

It sounds like everything is working, apart from roxygen 2.  This is the
right way to do this; there are many examples; for example findOverlaps for
GenomicRanges, GenomicRanges which support ignore.strand which is not an
argument to the generic; see below.  You may have to discuss this with the
roxygen developers; I don't use that framework.  But your general idea is
sound.

Best,
Kasper

> findOverlaps
standardGeneric for "findOverlaps" defined from package "IRanges"

function (query, subject, maxgap = 0L, minoverlap = 1L, type = c("any",
    "start", "end", "within", "equal"), select = c("all", "first",
    "last", "arbitrary"), algorithm = c("nclist", "intervaltree"),
    ...)
standardGeneric("findOverlaps")
<environment: 0x7fb7815a8518>
Methods may be defined for arguments: query, subject
Use  showMethods("findOverlaps")  for currently available ones.


> getMethod("findOverlaps", signature("GenomicRanges", "GenomicRanges"))
Method Definition:

function (query, subject, maxgap = 0L, minoverlap = 1L, type = c("any",
    "start", "end", "within", "equal"), select = c("all", "first",
    "last", "arbitrary"), algorithm = c("nclist", "intervaltree"),
    ...)
{
    .local <- function (query, subject, maxgap = 0L, minoverlap = 1L,
        type = c("any", "start", "end", "within", "equal"), select =
c("all",
            "first", "last", "arbitrary"), algorithm = c("nclist",
            "intervaltree"), ignore.strand = FALSE)
    {
        type <- match.arg(type)
        select <- match.arg(select)
        algorithm <- match.arg(algorithm)
        if (algorithm == "nclist")
            FUN <- findOverlaps_GenomicRanges
        else FUN <- findOverlaps_GenomicRanges_old
        FUN(query, subject, maxgap = maxgap, minoverlap = minoverlap,
            type = type, select = select, ignore.strand = ignore.strand)
    }
    .local(query, subject, maxgap, minoverlap, type, select,
        algorithm, ...)
}
<environment: namespace:GenomicRanges>

Signatures:
        query           subject
target  "GenomicRanges" "GenomicRanges"
defined "GenomicRanges" "GenomicRanges"


On Sun, Sep 20, 2015 at 1:23 PM, Christian Arnold <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
> Phone: +49(0)6221-387-8472
> Web: http://www.zaugg.embl.de/
>
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>

	[[alternative HTML version deleted]]