Opt-out of documenting an R6 method/field

[daattali]

Related to #1026

This is not a typical usecase, but I'm curious to see if you think it should be supported.

In a package, I have an R6 class Foo that I don't want to allow the user to instantiate directly. I have sort of a factory design pattern, meaning that I want the user to either call create_foo() or load_foo(), and these functions are responsible for instantiating a new Foo object. The user can then operate on this object.

I want to document all the public methods of this class, but because I'm not letting the user call Foo$new() directly, I don't want to document it. Currently I'm forced to give it some placeholder docs.

[hongooi73]

Well, there's nothing stopping you from not documenting the new method. Roxygen will throw a warning, but it will generate the Rd file anyway.

Apart from that, new still exists, which means people can still call it. There is a long history of people using undocumented stuff when they not supposed to, breaking things in the process, and causing headaches forever. You can't hide new, so the next best thing is probably to document it and tell them not to use it. That's what I do.

[daattali]

CRAN checks is what's stopping me from not documenting the method and its arguments. If my package would live on github only then I wouldn't care, but I just submitted it to CRAN today and they wouldn't be thrilled if I had that method undocumented.

In my usecase, I actually did disable the ability of end users to call $new() directly. I'm not using any weird undocumented features of R6, nothing that I'm doing is prone to break in the future, all I want to do is prevent people from creating the object directly and use a safe alternative. Everything about it works, I just hate that the documentation for the object has a big section for the new method and I just document every parameter with N/A - do not call this method directly, use foo() instead

[hongooi73]

I'm not talking about undocumented features of R6. I'm talking about undocumented features of YOUR code, namely your whateverclass$new method. And you don't prevent people from creating it directly, you just put a temporary obstacle in their way. Anyone who looks in your constructor function can figure out what's going on.

[daattali]

Yes, they can, and that's fine. The vast majority of users don't try to write code that goes around undocumented APIs, and for that majority userbase it'd be ideal if there wasn't a large chunk of the object docs that is just a filler with no information in it.

People can also access internal methods of packages with ::: and those functions don't need to be documented, and that's all good. I just don't want to be forced to document the $new() method. The ideal solution IMO would be a notion of a private constructor, so that only functions in my package can even instantiate the R6 class, but I don't think that will happen, so I think letting us not document $new() is a fair compromise.

[gaborcsardi]

R CMD check does not care if your R6 methods are documented or not, and also does not care about the warnings that roxygen throws, they are not running roxygen. So this is not an issue with CRAN.

I agree that it would be nice to be able to not document new(). We could use something like @describeIn NULL to tell roxygen to skip a method or field.

[daattali]

You're right @gaborcsardi , CRAN checks don't care. It's roxygen2 that gives me lots of warnings when I try to document. Those warnings make it feel like I'm doing something terribly wrong. I like your proposed solution.

> devtools::document()
Updating cometr documentation
Loading cometr
Writing NAMESPACE
Warning: [C:\Users\D\Documents\R\cometr\R\experiment.R:137] undocumented R6 method: `initialize`
Warning: [C:\Users\D\Documents\R\cometr\R\experiment.R:144] argument `experiment_key` undocumented for R6 method `initialize()`
Warning: [C:\Users\D\Documents\R\cometr\R\experiment.R:144] argument `experiment_url` undocumented for R6 method `initialize()`
Warning: [C:\Users\D\Documents\R\cometr\R\experiment.R:144] argument `api_key` undocumented for R6 method `initialize()`
Warning: [C:\Users\D\Documents\R\cometr\R\experiment.R:144] argument `keep_active` undocumented for R6 method `initialize()`
Warning: [C:\Users\D\Documents\R\cometr\R\experiment.R:144] argument `log_output` undocumented for R6 method `initialize()`
Warning: [C:\Users\D\Documents\R\cometr\R\experiment.R:144] argument `log_error` undocumented for R6 method `initialize()`

[hadley]

Note to self: implement post #1818. Make @noRd a method level tag that you can deliberately use to suppress the docs. Allow @field name NULL to suppress docs for a field. Also need to update rd-other.Rmd.