R6 classes support

[fkgruber]

R6 classes are new object oriented classes that also support pass-by-reference. See: http://cran.r-project.org/web/packages/R6/index.html

It seems that Roxygen could do something similar to what is doing with reference classes to get this working.

Is this something in the works already?

thanks
Fred

[imanuelcostigan]

Cross posted on R6 repo: r-lib/R6#3

[RyanHope]

Bump. I really want to try this but I need a way of creating good docs.

[daattali]

Just a bump to show my support for adding support for R6

[RyanHope]

Still no progress on this?

[imanuelcostigan]

Started work on https://github.com/imanuelcostigan/roxygen/tree/r6. But far too early to a submit a pull request. Comments and guidance (@hadley) welcome.

[hadley]

If anyone wanted to work on this, the place to start would be what the output should look like, i.e. what should the Rd file for a RC/R6 class look like?

[imanuelcostigan]

To begin with, here's an example of what roxygen is currently (as of 4.1.1) capable of processing:

#' RC implementation of Queue
#'
#' A simple example of what is possible using roxygen 4.1.1
#'
#' @field queue a list of items in the queue
#' @examples
#' (qrc <- QueueRC(5, 6, "foo"))
#' qrc$add("add something")
#' qrc$add("and something else")
#' qrc$remove()
#' @export

QueueRC <- setRefClass("Queue",
  fields = list(
    queue = "list"),
  methods = list(
    initialize = function (...) {
      "Initialises queue"
      for (item in list(...)) {
        add(item)
      }
    },
    add = function(x) {
      "Add x to the end of the queue"
      queue <<- c(queue, list(x))
      invisible(.self)
    },
    remove = function () {
      "Remove first item off the queue. Returns NULL of the queue is empty"
      if (length() == 0) return(NULL)
      head <- queue[[1]]
      queue <<- queue[-1]
      head
    },
    length = function () {
      "Returns the length of the queue"
      base::length(queue)
    }
  ))

The result is:

[imanuelcostigan]

ReferenceClasses have three key bits that require documentation:

1. Fields
2. Methods
3. Inheritance

Of these, roxygen is capable of doing 1 and 2 but not 3 (AFAIK).

In contrast, R6 has three key bits that should be documented:

1. Public members (fields and methods). I don't think private members need to or should be documented. Use comments for developers.
2. Active bindings
3. Inheritance
4. Portability

[RyanHope]

Simple docstring comments for each class menthod is not acceptable. There
needs to be a way to document the parameters of each methods.

On Mon, Aug 10, 2015 at 7:20 AM, Imanuel Costigan [email protected]
wrote:

ReferenceClasses have three key bits that require documentation:

1. Fields
2. Methods
3. Inheritance

Of these, roxygen is capable of doing 1 and 2 but not 3 (AFAIK).

In contrast, R6 has three key bits that should be documented:

1. Public members (fields and methods). I don't think private members
   need to or should be documented. Use comments for developers.
2. Active bindings
3. Inheritance
4. Portability

—
Reply to this email directly or view it on GitHub
#306 (comment).

Ryan Hope, M.S.
CogWorks Lab
Cognitive Science Department
Rensselaer Polytechnic Institute

[imanuelcostigan]

@RyanHope I agree. What I provided above is what is possible at the moment.

[hadley]

@RyanHope why don't you show an example of an Rd file that looks the way you want? Otherwise you're not contributing much to making this feature happen.

[RyanHope]

I think how R6 methods are documented is a bigger issue than what the
output looks like. For example, last time I tried, none of the @tokens that
would normally be parsed in the #' style comments work within the
docstrings. A solution that maintains consistency with how everything else
is documents would be nice.

On Tue, Aug 11, 2015 at 11:31 AM, Hadley Wickham [email protected]
wrote:

@RyanHope https://github.com/RyanHope why don't you show an example of
an Rd file that looks the way you want? Otherwise you're not contributing
much to making this feature happen.

—
Reply to this email directly or view it on GitHub
#306 (comment).

Ryan Hope, M.S.
CogWorks Lab
Cognitive Science Department
Rensselaer Polytechnic Institute

[hadley]

@RyanHope it is the only issue. If someone could present a reasonable starting place for what the output should look like it, I could make it happen. No one seems to be willing to put in any time thinking about it, so it's not high on my priorities.

[RyanHope]

I will put some time into this next week once I get back from a conference.

On Thu, Aug 13, 2015 at 9:25 AM, Hadley Wickham [email protected]
wrote:

@RyanHope https://github.com/RyanHope it is the only issue. If
someone could present a reasonable starting place for what the output
should look like it, I could make it happen. No one seems to be willing to
put in any time thinking about it, so it's not high on my priorities.

—
Reply to this email directly or view it on GitHub
#306 (comment).

Ryan Hope, M.S.
CogWorks Lab
Cognitive Science Department
Rensselaer Polytechnic Institute

[hadley]

If someone puts together a concrete proposal, please open a new issue.

[jameslamb]

For anyone else arriving here from Stack or Google...in the absence of first-class support in roxygen I've created this workaround: https://github.com/jameslamb/rsixygen

One day I'm going to come back here and drop a suggestion for doing this in roxygen but the few times I've tried I've found it really difficult to grok roxygen's internals.

Anyway, hope rsixygen might help some people a bit!