roxygen3 v0.1

by Hadley Wickham

In-source documentation for R

A Doxygen-like in-source documentation system for Rd, collation, and NAMESPACE. (This is the third rewrite)

Readme

NOTICE 28 November 2013

Roxygen development activity has shifted to roxygen2.

Previous README.md

Roxygen3 is a ground-up rewrite of roxygen2 aiming for a design that is simpler, more modular and easier to understand so that bugs can be fixed more rapidly and others can extend roxygen to meet their specific needs.

It is likely that roxygen3 will never be released on CRAN, but instead will be merged into roxygen2.

To try it out:

  # install.packages("devtools")
  library(devtools)
  install_github("devtools") # you need the latest version
  install_github("roxygen3")

  library(roxygen3)
  roxygenise("path/to/my/package")

New features

  • @export is much smarter - it will automatically figure out if you have an S3 method. It will also automatically export all the methods for a S3 generic.

  • @autoImports will automatically generate the appropriate import directives for all functions that your function uses. It will respect @importFrom directives if you need to manually resolve conflicts.

  • A new @dev tag flags a function as being more suitable for developers who want to build on top of your package than everyday users.

  • @useDynLib with no arguments will automatically figure out what the namespace directive should be. Additionally, arguments are no longer parsed so that you can use the full range of useDynLib directives.

  • Custom behaviour objects allow you to control exactly what tags, processors and writers are applied to the roxygen blocks. By modifying the default_behaviour() you can turn off tags that you don't want, or restrict the output to only Rd files, the NAMESPACE or the DESCRIPTION.

  • General S4 support is much improved and should work out of the box. There are also a number of tags that will help generate parts of the documentation: @classHierarchy, @classMethods, @genericMethods. These are not added automatically because standards for S4 documentation vary so much, so you can pick and choose what you want to use.

Developers guide

One of the main motivations for this rewrite of roxygen is to make it much easier to extend (and make it easier to fix bugs!). It has been rewritten to use S4, along with a much stronger object system that should make it easier to understand what's going on. The following section gives an overview of the important classes and generics. More detail will eventually be available in the class and generic documentation.

The best way to learn is by example - so make sure you have a source version of roxygen3 installed

Naming conventions:

  • S4 classes and constructors: AClass
  • S4 methods: aMethod
  • functions a_function

Class overview

  • The Block encapsulates information about all expressions in a package and the the documentation associated with them. Note that all top-level calls get roxygen block even if they don't have documentation. A block consists of a list of @tags, an @object that represents the object being documented, and a @srcref that provides the location of the documentation block.

    • A Tag object corresponds to a single roxygen tag: #' @tag text. Tag objects are created by the build_tag function and come preloaded with a @text slot. Tags that need richer data structures should define additional slots and fill them up with the value<- or process methods. Tags are also the unit at which output functions operator. See the Tags section for more details.

    • A Object represents the object that a block documents. It has subclasses NullObject (for blocks that don't document an object), FunctionObject, DataObject, PackageObject, S3GenericObject, S3MethodObject, S4GenericObject, S4MethodObject, S4ClassObject and R5ClassObject. These are created from the call that the block documents in object_from_call

    • A srcref is the S3 srcref object which stores a file and location of source code

  • A Bundle stores a list of blocks. There are currently two subclasses: DirectoryBundle and PackageBundle for representing all the blocks in a directory or package respectively. The main different between a package and directory is that a package has a name, and getting to the R code from the base paths are slightly different.

  • A Behaviour stores a list of Tags, a list of processors functions and a list of writer functions. These are used to control the output, and if you extend roxygen with new processors or writers, you will need to provide some way for users to easily create behaviours that use them.

    • Processors and writers are just functions that should accept a Bundle as the first argument. Processors should return a Bundle and writers should be run only for their side effects: creating files on disk. Writers will generally be S4 generics that break apart the bundle into blocks and tags - see the code for writeRd, writeNamespace and writeDescription for examples.

Tags

To implement a new tag for roxygen, you need to subclass Tag and implement the appropriate methods. For a simple tag, all you need to do is implement the value<- accessor and at least one output method. For more complex tags, you'll also need to implement the process method, and maybe the defaultTag method. These are described in more detail below:

  • value<- is used to initialize a tag from a text string. Use this to define basic parsing behaviour. It will be called with a character vector with one element for each occurence of tag in the documentation block. Most tags just break up into words and store in the common text slot.

  • process is called with the tag and the whole block and should return a block. Use this if the tag needs to add multiple tags to the output, or needs to access the object or srcref associated with the block. See the tag accessors for convenient ways to modify the tags in a block.

  • defaultTag provides an object specific way of adding default tags to a block. It is called with a tag and an object, and should return a new tag that will be added to the block if a user supplied tag of that name is not already present. This mechanism is used to automatically add @name, @rdname, @usage, @docType, and @defaultExport for all objects. (Note that this method is called using special dispatch and the tag object will never be supplied.)

Output:

writeRd, writeNamespace, and writeDescription return objects that will be used to modify Rd files, the NAMESPACE and DESCRIPTION respectively.

  • writeRd methods should return an Rd command object - these objects take care of the merging that occurs when multiple blocks are stored into the same file.

  • writeNamespace methods should return a character vector of namespace directives

  • writeDescription should return a named list containing character vectors of length one.

Functions in roxygen3

Name Description
AuthorTag-class @author: the author of the documentation
ClassHierarchyTag-class @classHierarchy: describe class hierarchy for an S4 object.
auto_dynlib Automatically determine the dynamic imports that a function needs.
Behaviour-class [DEV] An object representing processing behaviour.
add_s3_metadata Add S3 metadata to a function
auto_imports [DEV] Scans a function and determines what functions it uses from other packages.
Block-class [DEV] Block class.
Bundle-class [DEV] An object representing a bundle of blocks in multiple files.
AliasesTag-class @aliases: additional topic aliases.
AutoImportsTag-class @autoImport: automatically add import statements.
ConceptTag-class @concept: add a "concept" index entry.
DevTag-class @dev: flag a function as for developers only.
DebugTag-class @debug: show the input paths as an Rd comment.
DefaultExportTag-class @defaultExports: stores information used by @exports
DetailsTag-class @details: provide (lots of) extra detail about the function
default_behaviour [DEV] Encapuslate default behaviour.
defaultTag [DEV] Generate default tag.
ClassMethodsTag-class @classMethods: automatically list all methods of an S4 class.
CommentTag-class @comment: add comments to the Rd file.
DirectoryBundle-class [DEV] A bundle of files in a directory.
DocTypeTag-class @docType: set the documentation type of the object.
EncodingTag-class @encoding: specify non-standard encoding for Rd file
ExamplesTag-class @example/@examples: provide examples.
FormatTag-class @format: describe format of data.
GenericMethodsTag-class @genericMethods: automatically list all methods of a generic
ParamTag-class @param: describe input parameters
NoteTag-class @note: Add a note section.
object_from_call [DEV] Given a call that modifies the R environment, find the object that it creates.
parse_block Parse and execute a block of text in a package like environment.
RdnameTag-class @rdname: manually set the generated file name.
ReferencesTag-class ' @references: add references to the literature.
rPath Compute path to a bundle.
is_s3_generic [DEV] Determine if a function is an S3 generic or S3 method.
roxygenise Roxygenise a package.
S3methodTag-class Export S3 methods.
DescriptionTag-class @description:: describe the function in one or two paragraphs.
Object-class [DEV] The object being documented.
PackageBundle-class [DEV] A bundle of files in a package.
roxygen3 Roxygen3.
ReturnTag-class @return: describe the output of the function
SlotTag-class @slot: document the slots of a S4 class.
SourceTag-class @source: the source of a dataset
TextUsage-class Given an object, return a string showing how that object should be used.
TemplateTag-class Include documentation templates.
TagUsageTag-class @usageTag: describe how to use roxygen tags
FamilyTag-class @family: associate the function with a family to automatically add cross-references.
TitleTag-class @title: Override default topic title.
find_tags Find all currently defined tags.
NameTag-class @name: Override the default topic name.
NoRdTag-class Do not produce rd file for this object.
parse_directory Parse directory of source files.
SectionTag-class @section: Add a new named section.
parse_file Parse a source file containing roxygen blocks.
UsageTag-class @usage: describe the usage of a function.
CollateTag-class @include: describe files that should be sourced before this one.
IntroTag-class Title, description and details.
KeywordsTag-class @keywords: provide high-level keywords.
InheritParamsTag-class @inheritParams: Inherit parameters from another function.
RdCommand [DEV] Translate a command and expressions into an Rd expression; multiple expressions take their own braces.
process [DEV] Process bundles and blocks.
tag [DEV] Convenience methods for manipulating tags in a block.
Tag-class [DEV] Tag class
writeDescription [DEV] An output generator for the ‘DESCRIPTION’ file.
writeNamespace [DEV] An output generator for the ‘NAMESPACE’ file.
ExportClassTag-class Namespace: tags for exporting objects
SeealsoTag-class @seealso: other places to look for documentation.
writeRd [DEV] Output to Rd files in the man directory.
ImportClassesFromTag-class Namespace: tags for importing functions.
UseDynLibTag-class @useDynLib: import routines from a shared library.
No Results!

Details

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/roxygen3)](http://www.rdocumentation.org/packages/roxygen3)