Roxygen2: Inherit method documentation from R6 Superclass (even if overriding the method)

[s-fleck]

I hope I'm not overlooking an existing feature. It would be great if there were a mechanism for inheriting method- and field documentation from a superclass. For me it is a very common use-case to have several subclasses of the same base class that have a similar interface but vary in the implementation details. In the following case I would want to inherit the whole documentation for ProcessorSmart$run() from Processor$run(), even if I am overriding the $run() method:

#' An Abstract Class
#' @export
Processor <- R6::R6Class(
  "Processor",
  public = list(

#' Process a dataset
#' @param x a `data.frame`
#' @return a processed`data.frame`
    run = function(x) {
      stop("Not implemented")
    })
)

#' An Real Class
#' @export
ProcessorSmart <-  R6::R6Class(
  "ProcessorSmart",
  inherit = Processor,
  public = list(

    run = function(x){
        cat("implemented")
        x
    }
  )
)

edit: edited for clarity, as non-overridden methods are inherited already and link to the base class. Though It still would be great to have the actual method documentation repeated on the subclass documentation page instead of just a link.

[pat-s]

This applies especially to initalize() methods from subclasses in our use case.

When having 3+ subclasses, this becauses a major pain.
However, when this gets implemented it would be great if a diff could be made on which params to inherit in the end.
The subclass might not always inherit all params of the superclass method(s).

Example

TopClass: Param1, Param2,

subclass1: Param1, Param2, Param3

subclasss2: Param1, Param3

subclass3: Param1, Param2, Param4

Here I would hope that for subclass3 I would only need to document Param4 and only Param1 and Param2 (not Param3) would be auto-inherited.

[CGMossa]

To add to this, is it possible to:

• Link to R6? [Processor$run]
• Can one method in an R6 class @inheritParams from another method?

I think it is very cool with this new R6 documentation, but I am unsure of how in tune with the rest of roxygen2-features this documentation is.

[gaborcsardi]

We'll have inheritance from super or other classes etc. eventually. Unfortunately this requires rewriting much of the current inheritance implementations.

Link to R6? [Processor$run]

Yeah, this would be awesome, but also challenging with the current roxygen architecture. In general we want to support links to sections, methods, etc. so this is coming as well.

Can one method in an R6 class @inheritParams from another method?

Yes, just put the common docs in the main chunk:

@param tags that appear before the class definition are automatically inherited by all methods, if needed.

https://roxygen2.r-lib.org/articles/rd.html#r6

I think it is very cool with this new R6 documentation, but I am unsure of how in tune with the rest of roxygen2-features this documentation is.

If you are not sure about something, read the documentation first, and if you still have question ask them on RStudio's community forum.