[Roxygen-devel] Roxygen2 3.0.0

Discussion:

Hadley Wickham

2013-11-15 13:57:25 UTC

Hi all,

This is just a quick note to let you know that I'm moving towards a
new release of roxygen2, bringing in the most important new features
and bug fixes from roxygen3. The most important new features are:

* S4 support (generics, methods and classes), generating correct
aliases and usage statements

* Better S3 support, so that you can just do `@export`, not
`@S3method` or `@export` + `@method` depending on whether you're
documenting the function or just exporting the definition

* I've also fixed a number of bugs to do with namespaces, usages and
escaping, so generally the set of situations where you need to
manually specify usage should be much much smaller.

* I'm moving towards a system where you can turn off wrapping
(https://github.com/klutometis/roxygen/pull/142) - this will be opt-in
in the current version of roxygen, but will eventually become the
default. It's just too hard to get wrapping right automatically, and
it causes a lot of problems for new users.

You can see a complete list of changes at
https://github.com/klutometis/roxygen/blob/master/NEWS.

If you are using roxygen for S4 currently, I'd really appreciate it if
you'd try it out - you should now be able to remove any custom @alias
and @usage tags. You can try out the dev version with:

install.packages("devtools")
devtools::install_github("devtools")
devtools::install_github("roxygen", "klutometis")

You'll also need a development environment since roxygen2 now includes
a little C++ code for better escaping (and will probably include more
over time as identify performance benchmarks and move them to C++).

If you discover any bugs, please file at
https://github.com/klutometis/roxygen/issues. I'll also consider small
new features, but while roxygen2 is now in much better shape than it
was a couple of weeks ago, it's still not easy to add new features.

Hadley

--
Chief Scientist, RStudio
http://had.co.nz/

Carl Boettiger

2014-01-21 05:03:35 UTC

Permalink

Hi roxygen-list,

I'm having difficulty implementing S4 roxygen documentation. I have no
idea what the correct way to go about this is, so I am mostly extrapolating
from this [stackoverflow answer](
http://stackoverflow.com/questions/7356120/how-to-properly-document-s4-methods-using-roxygen2)
(Happy to get any pointers to other tutorials on the S4 roxygen too). I'm
currently stuck trying to document a "concatenate" method:

The method looks like this: (See the [full package](
https://github.com/ropensci/EML/tree/7d0f006cdcae2f89e667b2c4163083da52e6e147
))

#' @rdname c-methods
#' @aliases c,attribute,ANY-method
setMethod("c", signature("attribute"), function(x, ...)
new("ListOfattribute", list(x, ...)))

With which `devtools::document(".")` works just fine, but then `check(".")`
complains:

Error : /tmp/Rtmpu87hGh/Rbuild785f32a6d07b/EML/man/c-methods.Rd:
Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'EML'

Not sure why check should fail when document works, or what fields I need
to add.

As a side note, I find the roxygen documentation in the example above to be
uninformative to a human (i.e. not really in the spirit of literate
documentation), and rather tedious to enter when I have dozens of such
concatenate methods, etc. Without appreciating the details, it seems to me
that ideally some of this could be generated programmatically from the
method definition instead?

Thanks for any hints or suggestions.

Cheers,

Carl

Post by Hadley Wickham
Hi all,
This is just a quick note to let you know that I'm moving towards a
new release of roxygen2, bringing in the most important new features
* S4 support (generics, methods and classes), generating correct
aliases and usage statements
documenting the function or just exporting the definition
* I've also fixed a number of bugs to do with namespaces, usages and
escaping, so generally the set of situations where you need to
manually specify usage should be much much smaller.
* I'm moving towards a system where you can turn off wrapping
(https://github.com/klutometis/roxygen/pull/142) - this will be opt-in
in the current version of roxygen, but will eventually become the
default. It's just too hard to get wrapping right automatically, and
it causes a lot of problems for new users.
You can see a complete list of changes at
https://github.com/klutometis/roxygen/blob/master/NEWS.
If you are using roxygen for S4 currently, I'd really appreciate it if
install.packages("devtools")
devtools::install_github("devtools")
devtools::install_github("roxygen", "klutometis")
You'll also need a development environment since roxygen2 now includes
a little C++ code for better escaping (and will probably include more
over time as identify performance benchmarks and move them to C++).
If you discover any bugs, please file at
https://github.com/klutometis/roxygen/issues. I'll also consider small
new features, but while roxygen2 is now in much better shape than it
was a couple of weeks ago, it's still not easy to add new features.
Hadley
--
Chief Scientist, RStudio
http://had.co.nz/
_______________________________________________
Roxygen-devel mailing list
Roxygen-devel at lists.r-forge.r-project.org
https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel

--
Carl Boettiger
UC Santa Cruz
http://carlboettiger.info/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20140120/e4d920e2/attachment.html>

Hadley Wickham

2014-01-21 12:54:52 UTC

Permalink

Hi Carl,

That advice is totally out of date. You shouldn't need to do anything
special for S4 methods.

Hadley

Post by Carl Boettiger
Hi roxygen-list,
I'm having difficulty implementing S4 roxygen documentation. I have no idea
what the correct way to go about this is, so I am mostly extrapolating from
this [stackoverflow
answer](http://stackoverflow.com/questions/7356120/how-to-properly-document-s4-methods-using-roxygen2)
(Happy to get any pointers to other tutorials on the S4 roxygen too). I'm
The method looks like this: (See the [full
package](https://github.com/ropensci/EML/tree/7d0f006cdcae2f89e667b2c4163083da52e6e147))
setMethod("c", signature("attribute"), function(x, ...)
new("ListOfattribute", list(x, ...)))
With which `devtools::document(".")` works just fine, but then `check(".")`
Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'EML'
Not sure why check should fail when document works, or what fields I need to
add.
As a side note, I find the roxygen documentation in the example above to be
uninformative to a human (i.e. not really in the spirit of literate
documentation), and rather tedious to enter when I have dozens of such
concatenate methods, etc. Without appreciating the details, it seems to me
that ideally some of this could be generated programmatically from the
method definition instead?
Thanks for any hints or suggestions.
Cheers,
Carl

--
Carl Boettiger
UC Santa Cruz
http://carlboettiger.info/

--
http://had.co.nz/

Carl Boettiger

2014-01-21 20:08:28 UTC

Permalink

Hi Hadley,

That's great news!

Um, I'm still unclear on what information I do need to properly document
the S4 methods. Without adding any roxygen documentation, check is
unhappy, e.g.

Undocumented S4 methods:
generic 'c' and siglist 'codeDefinition'

What should I be doing here?

Post by Hadley Wickham
Hi Carl,
That advice is totally out of date. You shouldn't need to do anything
special for S4 methods.
Hadley

Post by Carl Boettiger
Hi roxygen-list,
I'm having difficulty implementing S4 roxygen documentation. I have no

idea

Post by Carl Boettiger
what the correct way to go about this is, so I am mostly extrapolating

from

Post by Carl Boettiger
this [stackoverflow
answer](

http://stackoverflow.com/questions/7356120/how-to-properly-document-s4-methods-using-roxygen2
)

Post by Carl Boettiger
(Happy to get any pointers to other tutorials on the S4 roxygen too).

I'm

Post by Carl Boettiger
The method looks like this: (See the [full
package](

https://github.com/ropensci/EML/tree/7d0f006cdcae2f89e667b2c4163083da52e6e147
))

Post by Carl Boettiger
setMethod("c", signature("attribute"), function(x, ...)
new("ListOfattribute", list(x, ...)))
With which `devtools::document(".")` works just fine, but then

`check(".")`

Post by Carl Boettiger
Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'EML'
Not sure why check should fail when document works, or what fields I

need to

Post by Carl Boettiger
add.
As a side note, I find the roxygen documentation in the example above to

Post by Carl Boettiger
uninformative to a human (i.e. not really in the spirit of literate
documentation), and rather tedious to enter when I have dozens of such
concatenate methods, etc. Without appreciating the details, it seems to

Post by Carl Boettiger
that ideally some of this could be generated programmatically from the
method definition instead?
Thanks for any hints or suggestions.
Cheers,
Carl
On Fri, Nov 15, 2013 at 5:57 AM, Hadley Wickham <h.wickham at gmail.com>

https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel

Post by Carl Boettiger
--
Carl Boettiger
UC Santa Cruz
http://carlboettiger.info/

--
http://had.co.nz/

Hadley Wickham

2014-01-21 20:10:39 UTC

Permalink

Um, I'm still unclear on what information I do need to properly document the
S4 methods. Without adding any roxygen documentation, check is unhappy,
e.g.
generic 'c' and siglist 'codeDefinition'
What should I be doing here?

Adding some documentation? ;)

You need to decide how to document the methods. There's basically three options:

* document methods with generic (only an option if you created the
generic) - @rdname generic
* document methods with class (only an option if you created the
class) @rdname class-classname (I think)
* document method in its own file (only suitable if it's a complex method)

Hadley

--
http://had.co.nz/

Carl Boettiger

2014-01-21 20:25:30 UTC

Permalink

Hadley,

Thanks for the quick reply. I'm afraid I'm still a bit over my head on
this one.

Since concatenate ("c") is neither a complex method nor my own generic, I
gather I need your middle option.

If I just do:

#' @rdname c-codeDefinition
setMethod("c", signature("codeDefinition"), function(x, ...)
new("ListOfcodeDefinition", list(x, ...)))

Then check complains about missing \name and \title for the method.

If I add a name and title:

#' concatenate
#'
#' concatenate
#' @rdname c-codeDefinition
setMethod("c", signature("codeDefinition"), function(x, ...)
new("ListOfcodeDefinition", list(x, ...)))

Check complains

* checking for code/documentation mismatches ... WARNING
Codoc mismatches from documentation object 'c,codeDefinition-method':
\S4method{c}{codeDefinition}
Code: function(x, ..., recursive = FALSE)
Docs: function(x, ...)
Argument names in code not in docs:
recursive

Which seems to suggest that I should be defining the arguments as
`function(..., recursive = FALSE)`, which does indeed match the
documentation shown by ?c. However if I do so, check really complains that
this format is incorrect:

Error in conformMethod(signature, mnames, fnames, f, fdef, definition) :
in method for ?c? with signature ?x="codeDefinition"?: formal arguments
(x = "codeDefinition", ... = "codeDefinition", recursive =
"codeDefinition") omitted in the method definition cannot be in the
signature

completely confused as how to document a concatenate method for S4,

Carl

Post by Hadley Wickham

Post by Carl Boettiger
Um, I'm still unclear on what information I do need to properly document

the

Post by Carl Boettiger
S4 methods. Without adding any roxygen documentation, check is unhappy,
e.g.
generic 'c' and siglist 'codeDefinition'
What should I be doing here?

Adding some documentation? ;)
* document methods with generic (only an option if you created the
* document methods with class (only an option if you created the
* document method in its own file (only suitable if it's a complex method)
Hadley
--
http://had.co.nz/

Hadley Wickham

2014-01-21 20:33:24 UTC

Permalink

Post by Carl Boettiger
setMethod("c", signature("codeDefinition"), function(x, ...)
new("ListOfcodeDefinition", list(x, ...)))
Then check complains about missing \name and \title for the method.

I meant @rdname class-codeDefinition - but you'll need to check that's
the name of the generated class file in man/

Post by Carl Boettiger
#' concatenate
#'
#' concatenate
setMethod("c", signature("codeDefinition"), function(x, ...)
new("ListOfcodeDefinition", list(x, ...)))
Check complains
* checking for code/documentation mismatches ... WARNING
\S4method{c}{codeDefinition}
Code: function(x, ..., recursive = FALSE)
Docs: function(x, ...)
recursive

If you do getGeneric("c") you see

function (x, ..., recursive = FALSE)
standardGeneric("c", .Primitive("c"))

so your method needs to be

setMethod("c", signature("codeDefinition"), function(x, ..., recursive
= FALSE) {
new("ListOfcodeDefinition", list(x, ...))
})

Though that's a bit suboptimal because it allows you to concatenate
together any objects with codeDefinitions, which is probably not what
you want. In particular you should probably handle
ListOfcodeDefinitions specially so that c() maintains its usual
flattening behaviour.

Next you need to provide enough documentation that check passes - if
you're documenting in a file with other components it's usually enough
to document all the params. Maybe:

#' @param x,... codeDefinitions to concatenate
#' @param recursive Needed for compatibility with generic, otherwise ignored

But it will depend on what else you're documenting in that file. I'm
not sure what's best practice here - a lot of S4 documentation is not
very easy to use.

Hadley

--
http://had.co.nz/