- name: aliases
  description: >
    Add additional aliases to the topic.

    Use `NULL` to suppress the default alias automatically generated by roxygen2.
  template: ' ${1:alias}'
  vignette: index-crossref
  recommend: true

- name: author
  description: >
    Topic author(s), if different from the package author(s).
  template: ' ${1:author}'
  recommend: true

- name: backref
  description: >
    Manually override the backreference that points from the `.Rd` file back to
    the source `.R` file. Only needed when generating code.
  template: ' ${1:path}'
  vignette: index-crossref

- name: concept
  description: >
    Add additional keywords or phrases to be included in the `help.search()`
    index. Each `@concept` should be a single term or phrase.
  template: ' ${1:concept}'
  vignette: index-crossref
  recommend: true

- name: describeIn
  description: >
    Document a function or method in the `destination` topic.
  template: ' ${1:destination} ${2:description}'
  vignette: reuse
  recommend: true

- name: description
  description: >
    A short description of the purpose of the function. Usually around
    a paragraph, but can be longer if needed.
  template: "\n${1:A short description...}\n"
  vignette: rd-functions
  recommend: true

- name: details
  description: >
    Additional details about the function. Generally superseded by instead
    using a level 1 heading.
  template: "\n${1:Additional details...}\n"
  vignette: rd-functions

- name: docType
  description: >
    Set documentation type. One of `data`, `package`, `class`, or `methods`.

    Usually added automatically; for expert use only.
  template: ' ${1:data|package|class|methods}'

- name: encoding
  description: >
    Override encoding of single `.Rd` file. No longer recommended since
    all documentation should use UTF-8.
  template: ' ${1:encoding}'

- name: eval
  description: >
    Evaluate arbitrary code in the package namespace and insert the results
    back into the block. Should return a character vector of lines.
  template: ' ${1:r-code}'
  vignette: reuse

- name: evalNamespace
  description: >
    Evaluate arbitrary code in the package namespace and insert the results
    into the `NAMESPACE`. Should return a character vector of directives.
  template: ' ${1:r-code}'
  vignette: namespace

- name: evalRd
  description: >
    Evaluate arbitrary code in the package namespace and insert the results
    back as into the block. Should return a character vector of lines.
  template: ' ${1:r-code}'
  vignette: reuse

- name: example
  description: >
    Embed examples stored in another file.
  template: ' ${1:path}.R'
  vignette: rd-functions
  recommend: true

- name: examples
  description: >
    Executable R code that demonstrates how the function works. Code must run
    without error.
  template: "\n${1:# example code}\n"
  vignette: rd-functions
  recommend: true

- name: examplesIf
  description: >
    Run examples only when `condition` is `TRUE`.
  template: " ${1:condition}\n${2:# example code}\n"
  vignette: rd-functions
  recommend: true

- name: export
  description: >
    Export this function, method, generic, or class so it's available
    outside of the package.
  vignette: namespace
  recommend: true

- name: exportClass
  description: >
    Export an S4 class. For expert use only; in most cases you should use
    `@export` so roxygen2 can automatically generate the correct directive.
  template: ' ${1:class}'
  vignette: namespace

- name: exportMethod
  description: >
    Export S4 methods. For expert use only; in most cases you should use
    `@export` so roxygen2 can automatically generate the correct directive.
  template: ' ${1:generic}'
  vignette: namespace

- name: exportPattern
  description: >
    Export all objects matching a regular expression.
  template: ' ${1:pattern}'
  vignette: namespace

- name: exportS3Method
  description: >
    Export an S3 method. Only needed when the method is for a generic from a
    suggested package. Use `@exportS3Method NULL` to suppress the missing
    export warning when it's a false positive, e.g. you're registering the 
    method some other way.
  template: ' ${1:package}::${2:generic}'
  vignette: namespace
  recommend: true

- name: family
  description: >
    Generate `@seealso` entries to all other functions in `family name`.
  template: ' ${1:family name}'
  vignette: index-crossref
  recommend: true

- name: field
  description: >
    Describe a R6 or refClass field.
  template: ' ${1:name} ${2:description}'
  vignette: rd-R6
  recommend: true

- name: format
  description: >
    Describe the type/shape of a dataset. If the dataset is a data frame,
    include a description of each column. If not supplied, will be
    automatically generated by `object_format()`.
  template: ' ${1:description}'
  vignette: rd-datasets
  recommend: true

- name: import
  description: >
    Import all functions from a package. Use with extreme care.
  template: ' ${1:package}'
  vignette: namespace

- name: importClassesFrom
  description: >
    Import S4 classes from another package.
  template: ' ${1:package} ${2:class}'
  vignette: namespace

- name: importFrom
  description: >
    Import specific functions from a package.
  template: ' ${1:package} ${2:function}'
  vignette: namespace
  recommend: true

- name: importMethodsFrom
  description: >
    Import S4 methods from a package.
  template: ' ${1:package} ${2:generic}'
  vignette: namespace

- name: include
  description: >
    Declare that `filename.R` must be loaded before the current file.
  template: ' ${1:filename}.R'
  recommend: true

- name: includeRmd
  description: >
    Insert the contents of an `.Rmd` into the current block. Superseded
    in favour of using a code chunk with a child document.
  template: ' man/rmd/${1:filename}.Rmd'
  vignette: reuse

- name: inherit
  description: >
    Inherit one or more documentation components from another topic.
    If `components` is omitted, all supported components will be inherited.

    Otherwise, specify individual components to inherit by picking one or
    more of `params`, `return`, `title`, `description`, `details`, `seealso`,
    `sections`, `references`, `examples`, `author`, `source`, `note`,
    and `format`.
  template: ' ${1:source} ${2:components}'
  vignette: reuse
  recommend: true

- name: inheritDotParams
  description: >
    Automatically generate documentation for `...` when you're passing dots
    along to another function. We recommend supplying explicit argument names
    for maximum clarity and consistency.
  template: ' ${1:source} ${2:arg1 arg2 arg3}'
  vignette: reuse
  recommend: true

- name: inheritParams
  description: >
    Inherit argument documentation from another function. Only inherits
    documentation for arguments that aren't already documented locally.
    Optionally followed by a list of argument names to include or exclude,
    using the same syntax as `@inheritDotParams`.
  template: ' ${1:source} ${2:arg1 arg2 arg3}'
  vignette: reuse
  recommend: true

- name: inheritSection
  description: >
    Inherit a specific named section from another topic.
  template: ' ${1:source} ${2:section name}'
  vignette: reuse
  recommend: true

- name: keywords
  description: >
    Add a standardised keyword, indexed by `help.search()`. These are generally
    not useful apart from `@keywords internal` which flags the topic as internal
    and removes from topic indexes.
  template: ' ${1:keyword}'
  vignette: index-crossref
  recommend: true

- name: md
  description: >
    Force markdown processing for a block.
  vignette: rd-formatting

- name: method
  description: >
    If ambiguous, clarify which generic an S3 method belongs too. Only needed
    in very rare cases.
  template: ' ${1:generic} ${2:class}'
  vignette: rd-S3
  recommend: true

- name: name
  description: >
    Define (or override the topic) name.

    Typically only needed for synthetic topics where you are documenting `NULL`.
  template: ' ${1:name}'

- name: noMd
  description: >
    Suppress markdown processing for a block.
  vignette: 'rd-formatting'

- name: noRd
  description: >
    Suppress `.Rd` generation for a block. Use for documentation
    blocks that should only be visible in the source code.
  vignette: rd-functions
  recommend: true

- name: note
  description: >
    Add an optional note. Now generally superseded by
    using a level 1 markdown heading.
  template: "\n"

- name: order
  description: >
    Override the default (lexigraphic) order in which multiple blocks
    are combined into a single topic.
  template: ' ${1:number}'
  vignette: reuse
  recommend: true

- name: param
  description: >
    Describe a function input. Should describe acceptable input types
    and how it affects the output. `description` is usually one or two
    sentences but can be as long as needed.

    Document multiple arguments by separating their names with commas
    without spaces.
  template: ' ${1:name} ${2:description}'
  vignette: rd-functions
  recommend: true

- name: prop
  description: >
    Describe an S7 class property that is not a constructor parameter.
  template: ' ${1:name} ${2:description}'
  vignette: rd-S7
  recommend: true

- name: R6method
  description: >
    Document an R6 method that can't be discovered by introspection,
    such as methods added via `$set()`.
  template: ' ${1:Class}$${2:method}'
  vignette: rd-R6
  recommend: true

- name: rawNamespace
  description: >
    Insert literal text directly into the `NAMESPACE`.
  template: ' ${1:namespace directives}'
  vignette: namespace

- name: rawRd
  description: >
    Insert literal text directly into the `.Rd` file.
  template: ' ${1:rd}'
  vignette: rd-functions

- name: rdname
  description: >
    Override the file name of generated `.Rd` file. Can be used to
    combine multiple blocks into a single documentation topic.
  template: ' ${1:topic-name}'
  vignette: reuse
  recommend: true

- name: references
  description: >
    Pointers to the related literature. Usually formatted like a bibliography.
  template: ' ${1:reference}'
  vignette: index-crossref
  recommend: true

- name: return
  description: >
    Describe the function's output. Superseded in favour of `@returns`.
  template: ' ${1:description}'
  vignette: rd-functions

- name: returns
  description: >
    Describe the function's output. Typically will be a 1-2 sentence
    description of the output type, but might also include discussion
    of important errors or warnings.
  template: ' ${1:description}'
  vignette: rd-functions
  recommend: true

- name: section
  description: >
    Add an arbitrary section to the documentation. Now generally superseded
    in favour of using a level 1 heading.
  template: " ${1:section title}: \n"
  vignette: rd-formatting

- name: seealso
  description: >
    Link to other related functions or urls. Usually a sentence or two, or
    a bulleted list.
  template: ' [${1:func}()]'
  vignette: index-crossref
  recommend: true

- name: slot
  description: >
    Describe the slot of an S4 class.
  template: ' ${1:name} ${2:description}'
  vignette: rd-S4
  recommend: true

- name: source
  description: >
    Describe where the dataset came from. Provide a link to the original
    source (if possible) and briefly describe any manipulation that you
    performed when importing the data.
  template: ' ${1:description}'
  vignette: rd-datasets
  recommend: true

- name: template
  description: >
    Use a roxygen2 template. Now superseded in favour of inline R code.
  template: ' ${1:path-to-template}'
  vignette: reuse

- name: templateVar
  description: >
    Define variables for use in a roxygen2 template.
  template: ' ${1:name} ${2:value}'
  vignette: reuse

- name: title
  description: >
    A one-line description of the function shown in various indexes.
    An explicit `@title` is not usually needed as by default it is taken from
    the first paragraph in the roxygen block.
  template: ' ${1:title}'
  vignette: rd-functions
  recommend: true

- name: usage
  description: >
    Override the default usage generated by roxygen2. Only needed when
    roxygen2 fails to correctly derive the usage of your function.
  template: ' ${1:fun}(${2:arg1, arg2 = default, ...})'
  vignette: rd-functions
  recommend: true

- name: useDynLib
  description: >
    Import compiled code from another package.
  template: ' ${1:package}'
  vignette: namespace
  recommend: true
