Roclet Extending the Standard rd Roclet — rdx

This roclet extends the standard rd roclet by allowing

to add permitted values and default values to the @param tag and
to add a caption and a description to examples.

Usage

rdx_roclet()

Details

The following tags are supported:

@permitted: Permitted values for the argument. Permitted value description which are used for several arguments/functions can be stored in inst/roxygen/rdx_meta.R. For example:
```
list(
  rdx_permitted_values = list(
    mode = "`\"first\"`, `\"last\"`",
    msg_type = "`\"none\"`, `\"message\"`, `\"warning\"`, `\"error\"`"
  )
)
```
The reference to the permitted values is done by specifying the name of the list element in square brackets, e.g., @permitted [mode].
@default: Default value for the argument. By default the default value from the function formals is displayed. This can be overwritten by using the @default tag.
@examplesx: This tag can be used to mark the beginning of the examples section but doesn't affect the output, i.e., it can be omitted.
@caption: Caption for the example. The caption is displayed as a subsection in the examples section. The caption can be followed by an arbitrary number of @info and @code tags.
@info: Description of the example.
@code: Code of the example.

By default, any warning or error issued by the example code causes the building of the documentation to fail. If this is expected, the condition can be added to the expected_cnds option of the @code tag. E.g.,
```
@code [expected_cnds = "warning"]
```

To use the roclet call roxygen2::roxygenise(roclets = "admiral::rdx_roclet") or add to the DESCRIPTION file:

Roxygen: list(markdown = TRUE, roclets = c("collate", "namespace", "admiraldev::rdx_roclet"))

For more information on roxygen2 roclets see the Extending roxygen2.

Examples

Using the custom tags

The id char_scalar used for the @permitted tag is defined in man/roxygen/rdx_meta.R.

See demo_fun() for a rendered version of the Rd code generated in the example.

roxygen2::roc_proc_text(
  rdx_roclet(),
  c(
    "#' A Demo Function",
    "#'",
    "#' This function is used to demonstrate the custom tags of the `rdx_roclet()`.",
    "#'",
    "#' @param x An argument",
    "#' @param number A number",
    "#' @permitted A number",
    "#' @param letter A letter",
    "#' @permitted [char_scalar]",
    "#' @default The first letter of the alphabet",
    "#' @examplesx",
    "#' @caption A simple example",
    "#' @info This is a simple example showing the default behaviour.",
    "#' @code demo_fun(1)",
    "#' @caption An example with a different letter",
    "#' @info This example shows that the `letter` argument doesn't",
    "#'   affect the output. ",
    "#' @code demo_fun(1, letter = \"b\")",
    "demo_fun <- function(x, number = 1, letter = \"a\") 42"
  ))
#> $demo_fun.Rd
#> 
#> 
#> \name{demo_fun}
#> \alias{demo_fun}
#> \title{A Demo Function}
#> \usage{
#> demo_fun(x, number = 1, letter = "a")
#> }
#> \arguments{
#> \item{x}{An argument
#>
#> \describe{
#> \item{Default value}{none}
#> }}
#>
#> \item{number}{A number
#>
#> \describe{
#> \item{Permitted values}{A number}
#> \item{Default value}{\code{1}}
#> }}
#>
#> \item{letter}{A letter
#>
#> \describe{
#> \item{Permitted values}{a character scalar, i.e., a character vector of length one}
#> \item{Default value}{The first letter of the alphabet}
#> }}
#> }
#> \description{
#> This function is used to demonstrate the custom tags of the \code{rdx_roclet()}.
#> }
#> \section{Examples}{
#> \subsection{A simple example}{
#>
#> This is a simple example showing the default behaviour.
#>
#> \if{html}{\out{<div class="sourceCode r">}}\preformatted{demo_fun(1)
#> #> [1] 42}\if{html}{\out{</div>}}}
#> \subsection{An example with a different letter}{
#>
#> This example shows that the \code{letter} argument doesn't
#> affect the output.
#>
#> \if{html}{\out{<div class="sourceCode r">}}\preformatted{demo_fun(1, letter = "b")
#> #> [1] 42}\if{html}{\out{</div>}}}}
#>
#>