Skip to content

Latest commit

 

History

History
329 lines (223 loc) · 12.7 KB

NEWS.md

File metadata and controls

329 lines (223 loc) · 12.7 KB
Raw

roxygen2 4.0.0

  • The internal parsers are no longer part of the public roxygen2 interface.

  • @section titles and @export tags can now only span a single line to prevent common bugs.

  • 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 carefully reading of .Rd files. (#183)

  • Roxygen2 will now 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.

  • Roxygen2 now adds a comment to all generated files so that you know they've been generated, and should not be hand edited.

  • Usage statements in generated roxygen statements non-longer contain non-ASCII characters and will be wrapped if long. (#180)

  • New @field tag for documenting the fields on a reference class. (#181)

  • 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)

roxygen2 3.1.0

Documentation for reference classes

It's now possible to document reference classes, using the "docstring" convention described in ?setRefClass. If you want to provide a short paragraph description of what a method does, make the first component of the message a string containing the description, e.g.:

setRefClass("A", methods = list(
  f = function(a, b) {
    "Take numbers \code{a} and \code{b} and add them together"
    a + b
  }
))

Unlike the documentation for R functions, the documentation for methods can be quite succinct.

Roxygen adopts the convention that documented methods are public, and will be listed in the man page for the object. Undocumented methods are private and will not be shown in the documentation. The methods for all superclasses are also listed, so that you don't need to flip through multiple pages of documentation to understand what you can do with an object. All documented methods will be placed in a bulleted list in a section titled "Methods", the method usage will be automatically prepended to the docstring.

Minor fixes and improvements

  • Fixes for Rcpp 0.11.0 compatibility.

  • roxygenise() now invisible returns a list of all files generated by individual roclets. This is useful for tools that want to figure out if there are extra files in the man/ directory.

  • is_s3_generic() now recognises group generics (#166).

  • Don't try and add parameters for data objects (#165).

  • Sort output of families using C locale (#171).

  • @family now escapes function names in references (#172).

roxygen2 3.0.0

Roxygen2 now fully supports S4 and RC (reference classes) - you should no longer need to manually add @alias or @usage tags for S4 classes, methods and generics, or for RC classes.

  • The default usage definitions are much better, generating the correct usage for data sets (#122), S3 methods (without additional @method tag), S4 generics, S4 methods, and for replacement (#119) and infix functions. Backslashes in function arguments in are correctly escaped. Usage statements also use a more sophisticated line wrapping algorithm so that they should cause fewer problems with the R CMD check line limit. (#89, #125).

  • S4 classes, S4 methods, and RC classes are given better default topics, and the file names corresponding to those topics are shorter.

  • S4 methods will automatically inherit parameter documentation from their generic.

  • @slot name description allows you to document the slots of a S4 class.

S3 support has also been improved: roxygen2 now figures out whether a function is a S3 method or generic. (In the rare cases it does so incorrectly, use @method to manually describe the generic and class associated with a method). This means you can remove existing uses of @method, and can replace @S3method with @export.

Roxygen now has support for package specific options through the Roxygen field in the DESCRIPTION. The value of the field should be R code that results in a list. Currently only wrap and roclet values are supported:

  • Turn off Rd re-wrapping with adding Roxygen: list(wrap = FALSE)

  • Change the default roclets by specifying Roxygen: list(roclets = c("collate", "rd"))

Roxygen 3.0 also includes a number of minor fixes and improvements:

  • Infix functions are now escaped correctly in the NAMESPACE. (Thanks to @crowding, #111)

  • roxygenise() now works more like devtools::document() and only ever works in the current directory. The arguments roxygen.dir, overwrite, copy.package and unlink.target have been deprecated due to potential data loss problems.

  • The collate roclet is no longer a roclet: it processes R files using custom code (only statically, not dynamically) and is designed to be executed before the code is sourced. Run update_collate() to update the Collate directive based on @include tags - if there are none present, a collate directive will not be generated.

  • @useDynLib now works with more possible specifications - if you include a comma in the tag value, the output will be passed as is. This means that @useDynLib mypackage, .registration = TRUE will now generate useDynLib(mypackage, .registration = TRUE) in the NAMESPACE. (#124)

  • inst directory not created by default (#56).

  • Explicitly depend on utils and methods packages to make roxygen compatible with Rscript (#72). Import digest package instead of depending on it.

  • Always use C locale when sorting NAMESPACE file or tags in .Rd files. This ensures a consistent ordering across systems (#127).

  • Templates with extension .r are supported on case-sensitive file systems (#115). Template variables now actually work (#160, thanks to @bronaugh).

  • Suppress default aliases, format and usage with @aliases NULL, @format NULL and @usage NULL.

roxygen2 2.2.2

  • Correctly use keyword datasets not dataset (Fixes #60)

  • Reference classes no longer given incorrect docType (data).

roxygen2 2.2.1

  • Use unicode escapes in test files so tests pass on all platforms.

  • Work around bug in gsub in C locale by manually specifying Encoding().

roxygen2 2.2

New features

  • Package docType will automatically add package alias, if needed. (Fixes #4)

  • Data docType will automatically add datasets keyword, default usage, and default format. (Fixes #5). Data docType automatically added to data objects.

  • New @encoding tag for manually setting non-ASCII encodings when needed. (Fixes #7)

Bug fixes

  • write.description() now tries much harder to respect users' original DESCRIPTION field formatting instead of forcibly re-wrapping certain fields at 60 characters.

  • @details and @description now work correctly

  • @useDynLib now works correctly:

     @useDynLib packageName routine1 routine2

    produces

     useDynLib(packageName, routine1)
 useDynLib(packageName, routine2)

    in the NAMESPACE file, instead of separate (wrong) useDynLib statements as before.

  • All namespace import directives now behave in the same way as the export directives, producing multiple single directives instead one multiple directive: @importClassesFrom pkg a b now produces importClassesFrom(pkg, a) and importClassesFrom(pkg, b)

  • In example files included with @example you can now use infix operators (e.g. %*%) or other things with %, because they will be preceded by a backslash in the Rd file. This behaviour was already in place for examples directly included with @examples.

  • Aliases are no longer quoted, and % is escaped with a backslash (Fixes #24). Names also have % escaped (Fixes #50)

  • Replacement functions (e.g. foo<-) now get correct usage statements: foo() <- value instead of foo()<-value. (Fixes #38)

  • Functions with no arguments now correctly get usage statements (Fixes #35)

  • Indentation in examples now preserved (Fixes #27)

  • roxygen2 will replace characters that are not valid in filenames with a character substitute, e.g. [] becomes sub, <- becomes set (Fixes #6)

  • Usage strings use non-breaking spaces to prevent string default values containing whitespace to be split across multiple lines. This may cause problems in the unlikely event that you have default value containing a non-breaking space (`"\uA0"') (Fixes #21)

  • Functions with quoted names now get correct usage statements (Fixes #41)

  • Objects that no longer exist are not documented (Fixes #42)

  • Errors now display file name and line number of roxygen block to help you find the problem. Thanks to code contributions from Renaud Gaujoux. (Fixes #13)

  • Documentation with no untagged text but with @title, @description and @details tags now produces correct output.

roxygen2 2.1

New features

  • package dependencies loaded automatically

  • added support for the @source tag

Bug fixes

  • NAMESPACE file no longer needs to exist

  • Collate field in DESCRIPTION no longer needs to exist

  • = now recognised as way of assigning functions

  • x$y <- function() {...} no longer causes error

  • @example no longer added extra new-lines.

  • Correct directory normalisation under windows fixes broken test.

  • A special thanks goes to Yihui Xie who contributed all of the fixes and improvements (bar one) in this version!

roxygen2 2.0

Major changes

  • now works with run-time details to give more accurate output. This requires that the source code that roxygen is documenting be loaded prior to documentation. roxygen will attempt to do so, but you need to ensure required packages are loaded.

    Run-time data fixes some long standing bugs where roxygen couldn't correctly figure out function usage. We are not aware of any cases where you still need to use the @usage tag.

  • written in idiomatic R, and uses S3 instead of a homegrown class system.

  • roclets build up an internal data structure instead of writing to disk directly. This means that you can now use the @rdname tag to merge documentation for multiple functions into one file, and that only unique namespace directives are written to NAMESPACE (which makes @importFrom much more useful).

  • some features have been removed, and may or may not (based on your feedback) be reincluded. These include the callgraph roclet, and R CMD roxygen, which only worked on some systems.

  • a templating system: use the @template tag to insert a brew template stored in man-roxygen. Template variables can be set using @templateVar name value and retrieved from within the template with <%= name %>

  • extensive use of caching to make repeated runs as fast as possible. To clear caches and guarantee a complete rebuild, use clear_caches().

  • parsing of "introduction" (the text before the first tag) has changed. Now the title consists of the first paragraph (i.e. all text before the first empty line), the second paragraph is the description and all others are put in the details. Any component can be overridden with @title, @description and @details as appropriate.

Minor changes

  • @name is always output as an alias, even if @aliases are used.

  • @export correctly uses @method to generate @S3method namespace directive

New tags

  • @rdname filename sets the output filename (without extension). Use for functions non-alphanumeric functions (e.g. [<-) or if you want to document multiple functions in one file

  • @template templatename includes a documentation template (see above)

  • @section Section title: contents includes a section with any title. Don't forget the colon! That separates the title of the section from its contents.

  • @description and @details tags allow you to specify description and details components in a template

  • @family family name automatically adds see-also cross-references between all functions in a family. A function can belong to multiple families.

  • @inheritParams name allows you to inherit the documentation for parameters from another function, either within the current package (function) or in any other installed package (package:function). Currently only supports single inheritance (i.e. you can't inherit from a function that inherits from another function), but you can have multiple @inheritParams tags.

  • @format has been implemented; it existed in the roxygen package but was actually ignored