From h.wickham at gmail.com Tue Mar 11 17:03:53 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Tue, 11 Mar 2014 11:03:53 -0500 Subject: [Roxygen-devel] Roxygen2 4.0.0 - pre release Message-ID: Hi all, I'm planning to push roxygen2 4.0.0 to CRAN in the next week or so. There are three main new features: * all outputs are flagged with a comment that indicates that roxygen2 produced them, and roxygen2 will not overwrite a file it didn't create. (This is the reason it's a major version bump) * Rd files are no longer wrapped by default * vignettes actually explain how to use roxygen2. I've included the complete release notes below, but I'd really appreciate if you'd devtools::install_github("klutometis/roxygen") and try it out on your packages. Please let me know if you encounter any new problems, or find the upgrade process confusing. Hadley # roxygen2 4.0.0 Roxygen2 4.0.0 is a major update to roxygen2 that makes provides enhanced error handling and considerably safer default behaviour. Now, roxygen2 will never overwrite a file that it did not create. This means that before you run it for the first time, you'll need to run `roxygen2::upgradeRoxygen()`. That will flag all existing files as being created by roxygen2. ## New features * Six vignettes provide a comprehensive overview of using roxygen2 in practice. Run `browseVignettes("roxygen2")` to access. * `@describeIn` makes it easier to describe multiple function in one file. This is especially useful if you want to document methods with their generic, or with a common class, but it's also useful if you want to document multiple related functions in one file (#185). * `@field` documents the fields on a reference class (#181). It works the same way as `@slot` for S4 classes. * Roxygen2 now adds a comment to all generated files so that you know they've been generated, and should not be hand edited. * Roxygen2 no longer wraps the text in Rd files by default, i.e. the default option is `wrap = FALSE` now. To override it, you have to specify a field `Roxygen: list(wrap = TRUE)` in `DESCRIPTION` (#178). ## Improved error handling * Roxygen2 will never overwrite a file that was not generated by roxygen2. This means that the first time you use this version of roxygen, you'll need to delete all existing Rd files. `roxygenise()` gains a clean argument that will automatically remove any files previously created by roxygen2. * Parsing is stricter: many issues that were previously warnings are now errors. All errors should now give you the line number of the roxygen block associated with the error. * Every input is now checked to make sure that you have matching braces (e.g. every `{` has a matching `}`). This should prevent frustrating errors that require careful reading of `.Rd` files (#183). * `@section` titles and `@export` tags can now only span a single line to prevent common bugs. * `@S3method` is deprecated - just use `@export` (#198). * Better error message if you try to document something other than NULL, an assignment, a class, a generic or a method (#194). ## Bug fixes and minor improvements * Remove unneeded codetools and tools dependencies. * Bump required Rcpp version to 0.11.0, and remove custom makefiles. * Non-syntactic argument names (like `_x`) are now surrounded by back-ticks in the usage (#191). * The internal parsers are no longer part of the public roxygen2 interface. * Usage statements in generated roxygen statements non-longer contain non-ASCII characters and will be wrapped if long (#180). * By default, reference classes now only document their own methods, not their methods of parents (#201). * Default aliases always include the original name of the object, even if overridden by `@name`. This also means that `A <- setClass("A")` will get two aliases by default: `A` and `A-class` (#202). Use `@aliases NULL` to suppress default alias. * Non-syntactic class names (like `<-`) are now escaped in the usage section of S4 methods (#205). -- http://had.co.nz/ From h.wickham at gmail.com Thu Mar 13 16:50:29 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Thu, 13 Mar 2014 10:50:29 -0500 Subject: [Roxygen-devel] Roxygen2 4.0.0 - pre release In-Reply-To: References: Message-ID: It's looking for a DESCRIPTION file in your working directory. Any chance you're running it from a different place? Hadley On Thu, Mar 13, 2014 at 10:39 AM, Timothy Bates wrote: > FYI, I installed, and ran the upgrade function, but got this error: > > devtools::install_github("klutometis/roxygen") > roxygen2::upgradeRoxygen() > Error: Doesn't look like a package > > > -- > You received this message because you are subscribed to the Google Groups > "devtools" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to rdevtools+unsubscribe at googlegroups.com. > For more options, visit https://groups.google.com/d/optout. -- http://had.co.nz/ From h.wickham at gmail.com Thu Mar 13 21:57:38 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Thu, 13 Mar 2014 15:57:38 -0500 Subject: [Roxygen-devel] Roxygen2 4.0.0 - pre release In-Reply-To: <07b4f245-5486-4cd9-9c95-0ce0bb087563@googlegroups.com> References: <07b4f245-5486-4cd9-9c95-0ce0bb087563@googlegroups.com> Message-ID: On Thu, Mar 13, 2014 at 12:02 PM, Timothy Bates wrote: > If I cd into the directory of a package under devtools control, then this > result obtains > >> roxygen2::upgradeRoxygen() > Error in file(con, "w") : cannot open the connection > In addition: Warning message: > In file(con, "w") : cannot open file './man/figures': Is a directory > > > In general, errors with suggestions would be great :-) > > Like "Doesn't look like a package: Perhaps you need to cd into a the Roxygen > folder?" or whatever How about: "This directory doesn't look like a package. Are you sure that you're in the right directory?" Hadley -- http://had.co.nz/ From h.wickham at gmail.com Wed Mar 19 17:55:25 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Wed, 19 Mar 2014 11:55:25 -0500 Subject: [Roxygen-devel] Roxygen2 4.0.0 - pre release In-Reply-To: References: Message-ID: On Wed, Mar 19, 2014 at 11:53 AM, Timothy Bates wrote: > I'm getting an error running document() which is > >> devtools::document() > Updating umx.twin documentation > Loading umx.twin > Using the default option wrap = FALSE since it was not specified in the > Roxygen field in DESCRIPTION > Error: Failure in roxygen block at build_twin.r:1 > @result, is an unknown key > > Line 1 is commented out... The only place @result occurs is on line 69 of > that file. > > #' x = rbind(satModel$top.expMeanMZ at result, satModel$top.expMeanDZ at result) > > So, two questions. what does the error "unknown key" mean? and why is the > error for line 1? Unknown key means that roxygen doesn't know what @result means - maybe you meant to use # instead of #' ? Unfortunately I can only localise errors to the block in which they occurred, not the specific line. Hadley -- http://had.co.nz/ From h.wickham at gmail.com Fri Mar 21 16:42:37 2014 From: h.wickham at gmail.com (Hadley Wickham) Date: Fri, 21 Mar 2014 10:42:37 -0500 Subject: [Roxygen-devel] Roxygen2 4.0.0 - pre release In-Reply-To: <9d4da8a8-03c2-4b63-b72f-0bfdababecfd@googlegroups.com> References: <9d4da8a8-03c2-4b63-b72f-0bfdababecfd@googlegroups.com> Message-ID: How about instead of "Failure in roxygen block at build_twin.r:1" it said "Failure in roxygen block beginning build_twin.r:1" ? The advantage of using the slightly cryptic filename:linenumber format is that (eventually) IDEs like Rstudio will autolink it so that you can jump straight to the source. Hadley On Wed, Mar 19, 2014 at 12:09 PM, Timothy Bates wrote: > Ah... might be better to say "somewhere past line x?" > > PS: the warning for default wrap is truncated for me... so it misses out the > helpful tip on getting rid of this > > So despite > >> getOption("warning.length") > [1] 1000 > I see > Using the default option wrap = FALSE since it was not specified in the > Roxygen field in DESCRIPTION > > Not the intended > Using the default option wrap = FALSE since it was not specified in the > Roxygen field in DESCRIPTION. To configure this explicitly, add the > following line to the DESCRIPTION file: `Roxygen: list(wrap = FALSE)` > > > On Wednesday, March 19, 2014 4:55:25 PM UTC, Hadley Wickham wrote: >> >> On Wed, Mar 19, 2014 at 11:53 AM, Timothy Bates >> wrote: >> > I'm getting an error running document() which is >> > >> >> devtools::document() >> > Updating umx.twin documentation >> > Loading umx.twin >> > Using the default option wrap = FALSE since it was not specified in the >> > Roxygen field in DESCRIPTION >> > Error: Failure in roxygen block at build_twin.r:1 >> > @result, is an unknown key >> > >> > Line 1 is commented out... The only place @result occurs is on line 69 >> > of >> > that file. >> > >> > #' x = rbind(satModel$top.expMeanMZ at result, >> > satModel$top.expMeanDZ at result) >> > >> > So, two questions. what does the error "unknown key" mean? and why is >> > the >> > error for line 1? >> >> Unknown key means that roxygen doesn't know what @result means - maybe >> you meant to use # instead of #' ? >> >> Unfortunately I can only localise errors to the block in which they >> occurred, not the specific line. >> >> Hadley >> >> -- >> http://had.co.nz/ > > -- > You received this message because you are subscribed to the Google Groups > "devtools" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to rdevtools+unsubscribe at googlegroups.com. > For more options, visit https://groups.google.com/d/optout. -- http://had.co.nz/