From cboettig at gmail.com Tue Jan 21 06:03:35 2014 From: cboettig at gmail.com (Carl Boettiger) Date: Mon, 20 Jan 2014 21:03:35 -0800 Subject: [Roxygen-devel] Roxygen2 3.0.0 In-Reply-To: References: Message-ID: 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 On Fri, Nov 15, 2013 at 5:57 AM, Hadley Wickham wrote: > 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/ > _______________________________________________ > 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: From h.wickham at gmail.com Tue Jan 21 13:54:52 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Tue, 21 Jan 2014 06:54:52 -0600 Subject: [Roxygen-devel] Roxygen2 3.0.0 In-Reply-To: References: Message-ID: Hi Carl, That advice is totally out of date. You shouldn't need to do anything special for S4 methods. Hadley On Mon, Jan 20, 2014 at 11:03 PM, Carl Boettiger wrote: > 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 > > > On Fri, Nov 15, 2013 at 5:57 AM, Hadley Wickham wrote: >> >> 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/ >> _______________________________________________ >> 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/ -- http://had.co.nz/ From cboettig at gmail.com Tue Jan 21 21:08:28 2014 From: cboettig at gmail.com (Carl Boettiger) Date: Tue, 21 Jan 2014 12:08:28 -0800 Subject: [Roxygen-devel] Roxygen2 3.0.0 In-Reply-To: References: Message-ID: 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? On Tue, Jan 21, 2014 at 4:54 AM, Hadley Wickham wrote: > Hi Carl, > > That advice is totally out of date. You shouldn't need to do anything > special for S4 methods. > > Hadley > > On Mon, Jan 20, 2014 at 11:03 PM, Carl Boettiger > wrote: > > 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 > > > > > > On Fri, Nov 15, 2013 at 5:57 AM, Hadley Wickham > wrote: > >> > >> 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/ > >> _______________________________________________ > >> 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/ > > > > -- > http://had.co.nz/ > -- Carl Boettiger UC Santa Cruz http://carlboettiger.info/ -------------- next part -------------- An HTML attachment was scrubbed... URL: From h.wickham at gmail.com Tue Jan 21 21:10:39 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Tue, 21 Jan 2014 14:10:39 -0600 Subject: [Roxygen-devel] Roxygen2 3.0.0 In-Reply-To: References: Message-ID: > 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? 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/ From cboettig at gmail.com Tue Jan 21 21:25:30 2014 From: cboettig at gmail.com (Carl Boettiger) Date: Tue, 21 Jan 2014 12:25:30 -0800 Subject: [Roxygen-devel] Roxygen2 3.0.0 In-Reply-To: References: Message-ID: 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 On Tue, Jan 21, 2014 at 12:10 PM, Hadley Wickham wrote: > > 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? > > 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 UC Santa Cruz http://carlboettiger.info/ -------------- next part -------------- An HTML attachment was scrubbed... URL: From h.wickham at gmail.com Tue Jan 21 21:33:24 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Tue, 21 Jan 2014 14:33:24 -0600 Subject: [Roxygen-devel] Roxygen2 3.0.0 In-Reply-To: References: Message-ID: > 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. I meant @rdname class-codeDefinition - but you'll need to check that's the name of the generated class file in man/ > 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 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/ From h.wickham at gmail.com Wed Jan 29 16:28:26 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Wed, 29 Jan 2014 09:28:26 -0600 Subject: [Roxygen-devel] Proposal for help operator for reference class methods Message-ID: Hi all, The code below implements a proposal for adding support for reference class methods to ?. If you think it looks reasonable, I'll forward on to Duncan Murdoch for further review, and hopefully inclusion in base R. The logic is rather complicated because of the many possible inputs, but basically: * If there's a help topic with alias class$method it will be shown * Otherwise show the doc string. Hadley rc_help <- function(call, where = parent.frame()) { call <- substitute(call) if (!identical(call[[1]], quote(`$`))) { stop("Not a RC method call") # In real help code this would happen elsewhere } stopifnot(is.name(call[[2]]), is.name(call[[3]])) class <- as.character(call[[2]]) method <- as.character(call[[3]]) # Figure out whether class is the name of a class or an object # This is complicated by the fact that the generator functions have # the same name as the class and are RC objects. is_class <- isClass(class, where = where) if (is_class) { classDef <- getClass(class, where = where) # Check it's a ref class if (!is(classDef, "refClassRepresentation")) { stop(class, " is not a reference class") } class_obj <- getRefClass(class) } else { # Must be an object if (!exists(class, envir = where)) { stop(class, " is not a class or an object") } obj <- get(class, envir = where) # Must be a reference lass if (!is(obj, "refClass")) { stop(class, " is not a reference class") } class <- class(obj) class_obj <- obj$getRefClass() } # Check that method is method of class if (!(method %in% class_obj$methods())) { stop(method, " not a method of ", class) } # Try rd file if available alias <- paste0(class, "$", method) topic <- help(alias) if (length(topic) > 0) { print(topic) } else { # No Rd file found, use docstring # Construct call to help, because it uses non-standard evaluation call <- substitute(class_obj$help(method), list(method = method)) eval(call) } } ClassA <- setRefClass("ClassA", methods = list( f = function() { "Some documentation" } )) ObjA <- ClassA() ClassB <- setClass("ClassB", contains = "list") ObjB <- ClassB() if (FALSE) { rc_help(ClassA$f) rc_help(ObjA$f) # Should fail: not reference classs rc_help(ClassB$f) rc_help(ObjB$f) # Should fail: doesn't exist rc_help(ClassC$f) rc_help(ClassA$g) rc_help(ObjA$g) } -- http://had.co.nz/