Roxygen2: Where is a comprehensive list of roxygen tags?

[grabear]

Problem

I've been searching for days to find a comprehensive list of roxygen tags... I have been unable to find one. There are R package cheat sheets, hadleys package documentation, rOpenSci package documentation, R's documentation, and others....

None of these documents has a comprehensive list of various roxygen tags or formatting tags. The only way to find these tags is to look in the source code in order to see what roxygen is parsing.

List of roxygen documentation links

• http://style.tidyverse.org/documentation.html
• https://www.rstudio.com/wp-content/uploads/2015/06/devtools-cheatsheet.pdf
• https://cran.r-project.org/doc/manuals/R-exts.html#Rd-format
• http://r-pkgs.had.co.nz/man.html
• https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html
• https://bookdown.org/rdpeng/RProgDA/documentation.html#help-files-and-roxygen2
• https://rstats-pkgs.readthedocs.io/en/latest/roxygen2.html
• https://cran.r-project.org/web/packages/roxygen2/vignettes/formatting.html
• https://ropensci.github.io/dev_guide/building.html#function-grouping
• https://colinfay.me/writing-r-extensions/writing-r-documentation-files.html#Marking-text

• http://kbroman.org/pkg_primer/pages/docs.html

  Further Questions and Remarks

• Where can I find a guide that has a table or dictionary of roxygen tags? I'd rather not have to read through multiple guides to figure out what's available. It's a bit ironic that an R documentation package doesn't have good documentation for it's syntax.

• Am I missing something?
• I'm not trying to be mean here. I'm just trying to understand how to use your package. I really think it's neat, but I can't seem to find any information after Googling for hours.
• Please take my criticisms lightly. :smile:

[grabear]

447

[hongooi73]

I think this is important. The external links are good, but generally they only rehash the most widely used tags. Here are some that I've seen in various repos but never documented anywhere:

#' @noRd
#' @evalRd
#' @md
#' @template
#' @reference

[joshua-theisen]

@grabear, have you been able to find a list of all the available tags?

[grabear]

@7670367 I haven't. I also haven't looked for this info for around 6 months.

[JakeVestal]

We might have to start making this if it truly doesn't already exist, even though it's pretty hard for me to believe that this documentation hasn't already been written by someone out there.

In my opinion, roxygen2 should have manpage results for all of the "@" tags such that, after loading the package, the user can pull up help, e.g.,

?`@eval`, ?`@examples`, ?`@param`

The tags fall into groups such as "function documentation", which would include @param, @export, @value and so on, so there doesn't need a manpage for every tag, but using ? on any tag should definitely bring up something in roxygen2.

[joshua-theisen]

Hadley's book has many of them, but arrange as prose on how to use them, not a comprehensive list. I pulled these out:
@param
@return
@examples
@tagName
@section
@title
@description
@seealso
@family
@aliases
@keywords
@example
@docType
@name
@method
@slot
@rdname
@describeIn
@include
@usage
@alias
@field
@inheritParams

Not sure if these should be included:
@export
@importFrom
@exportClass
@import
@importClassesFrom
@importMethodsFrom
@format
@source
@useDynLib
@Manual
@Article
@params

[grabear]

I've started a repository for this at https://github.com/datasnakes/roxygen-tags

[coatless]

So, the roxygen tags are given in two locations:

https://github.com/klutometis/roxygen/blob/c42a2f0ddb7006af5ce1f0462064a9c4424e510a/R/rd.R#L24-L66

https://github.com/klutometis/roxygen/blob/6b9582ac56002cd5c990530f603fe1bf987c3bbe/R/namespace.R#L58-L74

@hadley Would you be okay if I sent a PR that:

1. Surfaced tag names via roclet_display_tags()
2. Added another vignette providing use cases of the tags?

[hadley]

names(roxygen2:::default_tags()) will give you a complete list.

I'm not sure where the best place to document these is; probably in vignettes?

[hadley]

It would be very useful if someone would cross-reference names(roxygen2:::default_tags()) with the tags in https://roxygen2.r-lib.org/articles/namespace.html and https://roxygen2.r-lib.org/articles/rd.html and made a list for me to document.

[hadley]

The vignettes should now cover everything important. Please file specific issues if you notice missing tags.

[stla]

names(roxygen2:::default_tags()) will give you a complete list.

Hello. Looks like this function is not available anymore. Does anybody know where to find the complete list of tags?

[stla]

Here is the list of the tags I was able to find:

c(
  "@alias",
  "@aliases",
  "@assignee",
  "@author",
  "@backref",
  "@callGraph",
  "@callGraphDepth",
  "@callGraphPrimitives",
  "@concept",
  "@describeIn",
  "@description",
  "@details",
  "@docType",
  "@encoding",
  "@evalNamespace",
  "@evalRd",
  "@example",
  "@examples",
  "@export",
  "@exportClass",
  "@exportMethod",
  "@exportPattern",
  "@family",
  "@field",
  "@formals",
  "@format",
  "@import",
  "@importClassesFrom",
  "@importFrom",
  "@importMethodsFrom",
  "@include",
  "@inherit",
  "@inheritDotParams",
  "@inheritParams",
  "@inheritSection",
  "@keywords",
  "@md",
  "@method",
  "@name",
  "@noMd",
  "@noRd",
  "@note",
  "@param",
  "@rawNamespace",
  "@rawRd",
  "@rdname",
  "@references",
  "@return",
  "@S3method",
  "@section",
  "@seealso",
  "@setClass",
  "@slot",
  "@source",
  "@template",
  "@templateVar",
  "@title",
  "@TODO",
  "@usage",
  "@useDynLib"
)

I found some of them elsewhere, such as @callGraph. Is it a valid tag?

[gaborcsardi]

The NAMESPACE related tags are in https://roxygen2.r-lib.org/articles/namespace.html and the Rd related ones are in https://roxygen2.r-lib.org/articles/rd.html

[stla]

Thank you @gaborcsardi . Yes I saw these links but the tags are not listed. I was looking for a R vector of the tag names, as in my previous comment.

[mmuurr]

I realize this is closed, but +1 for an exhaustive list with usage somewhere. It's not obvious which tags take what arguments, and how they should be provided. @export, for example, has a default behavior when used with no arguments, but behaves differently when used with arguments.

As another example, @field _requires_ the name of the field to be specified in R6 documentation. In actually requires the name to be duplicated, in a sense, since roxygen2 won't throw an error if the @field name doesn't actually match the true name of the field):

Foo <- R6::R6Class("Foo",
  active = list(
    ## doesn't work, but I think is the natural thing to try to do:
    #' @field description of val1
    val1 = function() {...},

    ## works, but perhaps isn't intuitive, since other @tags know their 'context' (@export, for example)
    #' @field val2 description of val2
    val2 = function() {...}
  )
)

I find to get an understanding of some tags, I've been relying on reading through roxygen2's testthat tests in this repo ... which probably isn't the norm for most users.

I'd be more than happy to help curate such a page/list. I believe most users would find it to be a great resource (as opposed to trying to refer back to various vignettes as a look-up reference ... which, ironically, is the main point of roxygen2 :-)

[gaborcsardi]

I seems to me that @export is pretty well documented: https://roxygen2.r-lib.org/articles/namespace.html#exports
But specific issues and PRs for improvements are always welcome.

R6 and @field also has an example here: https://roxygen2.r-lib.org/articles/rd.html#r6

I wonder if the issue is that people don't find the articles at https://roxygen2.r-lib.org/index.html

Related open issues: #1080, #1165.

[krlmlr]

I like how renv handles the documentation for its various options, settings, and paths: e.g. ?options lists the available options. Should roxygen2 adopt a ?tags help page, that perhaps links to ?rd-tags and ?namespace-tags ?

[mmuurr]

@gaborcsardi certainly the vignettes are very helpful, but it's difficult to see all the variants listed/enumerated in the context of a vignette's prose. As another example, I 'discovered' the @export sym1 sym2 sym3 ... pattern only by reading code from others. But when seeing such patterns, one is now faced with the question: "Is this an _officially_ supported usage pattern, or is this a bugfeature that may be silently disabled in the future?"

@krlmlr re: renv, +1! This page, for example, is very helpful (especially as a lens into the workings of renv, which helps immensely in self-service debugging/repair when things inevitably don't go perfectly as planned :-)

In any case, I'm happy to take a first stab at building such a reference topic, provided y'all think it'd be a useful addition.

[gaborcsardi]

As another example, I 'discovered' the @export sym1 sym2 sym3 ... pattern only by reading code from others. But when seeing such patterns, one is now faced with the question: "Is this an officially supported usage pattern, or is this a bugfeature that may be silently disabled in the future?"

It is not in the documentation, so the best is to assume that it is not officially supported.