Use roxygen for help documentation

[andrie]

Andrie said:

Do you think it’s possible to use roxygen to document the package? I think this is easier in the long run, but I have no idea how this will work with R6 functions.

Antonio said:

I think it would clash with the export stuff, but I am not an R6 expert, so I am not sure. The problem is that roxygen doesn't work with R unless you use a subset of it. Since I use higher order functions, and there is no way of documenting a dynamically generated one, it can't be used with most of my code, azureml being no exception. The whole design of roxygen is anti-modular and inspired by an inferior static language that forces people to use preprocessors. I am just waiting patiently for the moment Roxygen fades away.

Andrie says: I think there is a way to get the best of both worlds. Not having to learn latex must be a benefit. I'll do some experiments to see if I can convert your .rd files into sensible roxygen.

[andrie]

Some pointers for documenting R6 classes at r-lib/R6#3

#' An example R6 class
#' 
#' @docType class
#' @importFrom R6 R6Class
#' @export
#' @format An \code{\link{R6Class}} generator object
#' @keywords data

myR6Class <- R6Class("myR6Class",
  ...
)

[piccolbo]

First, there are no Rd files quite yet, so conversion is impossible. Second, thinking it over, I am almost sure that all the functions created with webapi, which are not compatible with roxygen as they are dynamically generated, represent a lower level of this package that should not be exported or have user-level documentation. Third, I am getting more convinced by your idea of writing a layer of methods for generic function on top of the R6 methods, so the workaround you point to, albeit interesting, may not be necessary. So I propose we define the API and we leave this on hold for the moment. If it's all S3 generics, then we know how to use roxygen. Otherwise we need to follow the technique at the link you found, most likely.

[piccolbo]

Documentation written in "latex" as you call it. Now you can switch to Roxygen, or move on.

[andrie]

This branch is now merged back into master

[andrie]

R CMD check throws lots of warnings in documentation. Now that we are using roxygen2, it is easier to inherit parameters. I'll be working on this next.

[andrie]

Completed conversion to roxygen2. No documentation warnings or notes when running R CMD check.

[piccolbo]

There is too much visibility to methods. Can we avoid /name and /alias with the method written out explicitly (as.data.frame.Dataset). I know we get some warnings, but we can't document things that the user should not and can not type -- because methods are not exported, and rightfully so. It's a terrible user experience in exchange for no warnings -- to me it's a no brainer.

[andrie]

I'll see what I can do. I presume your objection is that the methods show up in the package help index page - and I agree with this objection.

However, this package probably needs to go on CRAN in due course, and this means we have to remove all warnings.

The way I've dealt with that in other projects is to write a package help page that lists the most important functions, so the user is less dependent on the index page itself.