R6 class support

[gaborcsardi]

This is far from being ready, I am opening it for discussion. Feedback is welcome.

Still coming:

• consistent naming of the initialize() / new() method
• support for fields, right now they have to be documented manually, via @field.
• support for active bindings, they are manual for now, via @field as well.
• add inheritance information, i.e. link to superclasses
• get rid of the compulsory @details tag, in the main part and also before a method (maybe later)
• support @description as well
• change method docs order: 1. Description 2. Usage 3. Arguments 4. Details.
• check that all public methods are documented
• check that docs and names(formals()) of method arguments match
• allow inheritParams() from methods (maybe later)
• allow inheritSection() from methods, maybe (maybe later)
• allow @inheritDotParams() from methods (maybe later)
• allow documenting a common argument up front in the class, and then automatically use this in the documentation of the methods
• A test(that) helper to run the code in the examples, because these do not
  run in R CMD check.
• Dump all the methods examples into a big \examples{} block at the end, so
  they are tested.
• should we used \describe{} for the list of arguments? Probably....
• actually arguments are in a table, so we should do that instead...
• support methods added via set(). (maybe layer)
• support user defined clone() methods. (maybe later)
• support documenting private methods, fields, active bindings? (maybe later)
• test cases
• documentation
• a vignette? (maybe later)
• check what CSS or other updates pkgdown needs to format the reference pages well.
• Fix paragraphs in argument blocks, because they are not wrapped currently.
• Format warnings the usual roxygen way.

This is the current syntax:

#' R6 class for a person
#' 
#' Description of the class.
#' 
#' @details
#' Details of the class.
#' 
#' @section Public fields:
#' * `name`: first name.
#' * `hair`: hair color.

Person <- R6Class("Person",
  public = list(
    name = NULL,
    hair = NULL,

    #' @details
    #' Create a new `Person` object.
    #' 
    #' @param name First name.
    #' @param hair Hair color, if known.
    #' @return A person object.
    #' 
    #' @examples
    #' Person$new("Ann", "black")

    initialize = function(name = NA, hair = NA) {
      self$name <- name
      self$hair <- hair
      self$greet()
    },

    #' @details
    #' Set new hair color.
    #' 
    #' @param val The new hair color.
    #' @return The new color, invisibly.
    #' 
    #' @examples
    #' ann <- Person$new("Ann", "black")
    #' ann$hair
    #' ann$set_hair("red")
    #' ann$hair

    set_hair = function(val) {
      self$hair <- val
    },

    #' @details
    #' Make the person greet.
    #' 
    #' @examples
    #' ann <- Person$new("Ann", "black")
    #' ann$greet()

    greet = function() {
      cat(paste0("Hello, my name is ", self$name, ".\n"))
    }
  )
)

This will generate the following:

Person               package:pkgdepends                R Documentation

R6 class for a person

Description:

     Description of the class.

Details:

     Details of the class.

Public fields:

        • ‘name’: first name.

        • ‘hair’: hair color.

Methods:

  Public methods:

         • ‘Person$new()’

         • ‘Person$set_hair()’

         • ‘Person$greet()’

  Method 'new()':

       Person$new(name = NA, hair = NA)

     Create a new ‘Person’ object.

    Arguments:

           • ‘name’: First name.

           • ‘hair’: Hair color, if known.


    Returns:

         A person object.


    Examples:

         Person$new("Ann", "black")


  Method 'set_hair()':

       Person$set_hair(val)

     Set new hair color.

    Arguments:

           • ‘val’: The new hair color.


    Returns:

         The new color, invisibly.


    Examples:

         ann <- Person$new("Ann", "black")
         ann$hair
         ann$set_hair("red")
         ann$hair


  Method 'greet()':

       Person$greet()

     Make the person greet.

    Examples:

         ann <- Person$new("Ann", "black")
         ann$greet()

This is how it looks in RStudio:

It could look, nicer, e.g. with some extra CSS:

Closes #388.

[gaborcsardi]

Apart from the "usual" @inheritParams, it seems like it would be useful to be able to document the same parameter for several methods up front. I'll add this to the list.

[sckott]

What about examples? Seems like maybe \examples in man files is needed so that cmd check & devtools::run_examples will run examples? Maybe devtools::run_examples could find and run the \subsection{Examples}{...} sections created by the doc sections in R6 public methods?

[gaborcsardi]

@sckott You can have @examples in the main block, e.g. to showcase all/most of the methods, and that'll be \examples{} in the man page, and CRAN will be happy as well.

[sckott]

right, that's what I currently do. Should best practice be then to not have examples in public method blocks since they could not be working examples?

[gaborcsardi]

Should best practice be then to not have examples in public method blocks since they could not be working examples?

IDK, I think I want to have examples for the methods sometimes, and then have a helper among the test cases to make sure that they run.

You still cannot run them with example(), but that seems tricky to fix.

[gaborcsardi]

@sckott Now we also dump all the method examples into a large \examples{} block at the end, so it is tested by R CMD check and no helpers etc. are needed.

[gaborcsardi]

@hadley All TODO list items are done.

[hadley]

Thanks @gaborcsardi!!

[wch]

Awesome!