Documents your conditions() and conditions()
Arguments
- package
The package to document
- registry
The name of the registry
- file
The file to save the documentation. This can be a file path, a connection object, or
NULL. Whenfileis a path, the directory of the path is searched for files containing# % Generated by cnd: do not edit by hand. These are removed if they are not the same as the generated documentation.- cleanup
If
FALSEwill not remove files containing# % Generated by cnd: do not edit by hand- fun
The name of a function
Value
cnd_document()Conditional on thefileargument:when
fileis a connection, the connection objectwhen
fileis a path, the pathwhen
fileisNULL, acharactervector of the documentationif no conditions are found, a warning is thrown and
NULLis returned
cnd_section()Acharactervector of the documentation
conditions
Conditions are generated through the {cnd} package.
The following conditions are associated with this function:
cnd:cnd_document_conditions/warningDocumentation will fail when no conditions are found. You may be executing
cnd_document()too early, before conditions have been registered. You can try to find your conditions withconditions().cnd:cnd_document_file/errorThe
fileargument tocnd_document()must be a file path, a connection object, orNULLto return the documentation as a character vector. The default value should be suitable for standard use cases.cnd:cnd_document_pkg_reg/errorBoth
packageandregistrymust be set to document conditions.You can set a registry by addingcnd_create_registry()calls to your package code.cnd:cnd_generated_cleanup/messageSome files created during the documentation process may become obsolete while updating your conditions.
cnd:cnd_generated_write/conditionThis condition is signaled when
cnd_document()needs to write new documentation files.
For more conditions, see: cnd-cnd-conditions
Examples
file <- file()
cnd_document("cnd", file = file)
readLines(file)
#> [1] "#' @name cnd-cnd-conditions"
#> [2] "#' @aliases cnd-cnd-conditions cnd:as_character_cnd_error cnd:cnd_document_conditions cnd:cnd_document_file cnd:cnd_document_pkg_reg cnd:cnd_generated_cleanup cnd:cnd_generated_write cnd:cond_cnd_class cnd:condition_message_generator cnd:condition_overwrite cnd:conditions_dots cnd:invalid_condition cnd:invalid_condition_message cnd:match_arg cnd:no_package_exports as_character_cnd_error cnd_document_conditions cnd_document_file cnd_document_pkg_reg cnd_generated_cleanup cnd_generated_write cond_cnd_class condition_message_generator condition_overwrite conditions_dots invalid_condition invalid_condition_message match_arg no_package_exports cnd:as_character_cnd_error/error cnd:cnd_document_conditions/warning cnd:cnd_document_file/error cnd:cnd_document_pkg_reg/error cnd:cnd_generated_cleanup/message cnd:cnd_generated_write/condition cnd:cond_cnd_class/error cnd:condition_message_generator/error cnd:condition_overwrite/warning cnd:conditions_dots/warning cnd:invalid_condition/error cnd:invalid_condition_message/error cnd:match_arg/error cnd:no_package_exports/warning"
#> [3] "#' @title Conditions for `cnd`"
#> [4] "#'"
#> [5] "#' @details"
#> [6] "#' The following conditions are defined in the `{cnd}` package."
#> [7] "#'"
#> [8] "#' @section [`{cnd}`][cnd-package]:"
#> [9] "#' These conditions are made with the `{cnd}` package though the use of"
#> [10] "#' [cnd::condition()]."
#> [11] "#'"
#> [12] "#' @section `{cnd}` conditions:"
#> [13] "#'"
#> [14] "#' \\subsection{`cnd:as_character_cnd_error/error`}{"
#> [15] "#' \\describe{"
#> [16] "#' \\item{package}{`{cnd}`}"
#> [17] "#' \\item{class}{`cnd:as_character_cnd_error`}"
#> [18] "#' \\item{type}{**error**}"
#> [19] "#' }"
#> [20] "#' You cannot coerce a [cnd::condition_generator] object to a character. This may have occurred when trying to put a condition function through [stop()] or [warning]. Instead, call the function first, then pass the result to [stop()] or [warning()]."
#> [21] "#'"
#> [22] "#' For example:"
#> [23] "#' ```r"
#> [24] "#' # Instead of this"
#> [25] "#' stop(my_condition)"
#> [26] "#'"
#> [27] "#' # Do this"
#> [28] "#' stop(my_condition())"
#> [29] "#' ```"
#> [30] "#' }"
#> [31] "#' \\subsection{`cnd:cnd_document_conditions/warning`}{"
#> [32] "#' \\describe{"
#> [33] "#' \\item{package}{`{cnd}`}"
#> [34] "#' \\item{class}{`cnd:cnd_document_conditions`}"
#> [35] "#' \\item{type}{**warning**}"
#> [36] "#' }"
#> [37] "#' Documentation will fail when no conditions are found. You may be executing [cnd::cnd_document()] too early, before conditions have been registered. You can try to find your conditions with [cnd::conditions()]."
#> [38] "#' }"
#> [39] "#' \\subsection{`cnd:cnd_document_file/error`}{"
#> [40] "#' \\describe{"
#> [41] "#' \\item{package}{`{cnd}`}"
#> [42] "#' \\item{class}{`cnd:cnd_document_file`}"
#> [43] "#' \\item{type}{**error**}"
#> [44] "#' }"
#> [45] "#' The `file` argument to [cnd::cnd_document()] must be a file path, a connection object, or `NULL` to return the documentation as a character vector. The default value should be suitable for standard use cases."
#> [46] "#' }"
#> [47] "#' \\subsection{`cnd:cnd_document_pkg_reg/error`}{"
#> [48] "#' \\describe{"
#> [49] "#' \\item{package}{`{cnd}`}"
#> [50] "#' \\item{class}{`cnd:cnd_document_pkg_reg`}"
#> [51] "#' \\item{type}{**error**}"
#> [52] "#' }"
#> [53] "#' Both `package` and `registry` must be set to document conditions.You can set a registry by adding [cnd::cnd_create_registry()] calls to your package code."
#> [54] "#' }"
#> [55] "#' \\subsection{`cnd:cnd_generated_cleanup/message`}{"
#> [56] "#' \\describe{"
#> [57] "#' \\item{package}{`{cnd}`}"
#> [58] "#' \\item{class}{`cnd:cnd_generated_cleanup`}"
#> [59] "#' \\item{type}{**message**}"
#> [60] "#' }"
#> [61] "#' Some files created during the documentation process may become obsolete while updating your conditions."
#> [62] "#' }"
#> [63] "#' \\subsection{`cnd:cnd_generated_write/condition`}{"
#> [64] "#' \\describe{"
#> [65] "#' \\item{package}{`{cnd}`}"
#> [66] "#' \\item{class}{`cnd:cnd_generated_write`}"
#> [67] "#' \\item{type}{**condition**}"
#> [68] "#' }"
#> [69] "#' This condition is signaled when [cnd::cnd_document()] needs to write new documentation files."
#> [70] "#' }"
#> [71] "#' \\subsection{`cnd:cond_cnd_class/error`}{"
#> [72] "#' \\describe{"
#> [73] "#' \\item{package}{`{cnd}`}"
#> [74] "#' \\item{class}{`cnd:cond_cnd_class`}"
#> [75] "#' \\item{type}{**error**}"
#> [76] "#' }"
#> [77] "#' [cnd::cnd()] simple calls the appropriate function: [stop()], [warning()], or [message()] based on the `type` parameter from [cnd::condition()]."
#> [78] "#' }"
#> [79] "#' \\subsection{`cnd:condition_message_generator/error`}{"
#> [80] "#' \\describe{"
#> [81] "#' \\item{package}{`{cnd}`}"
#> [82] "#' \\item{class}{`cnd:condition_message_generator`}"
#> [83] "#' \\item{type}{**error**}"
#> [84] "#' }"
#> [85] "#' [cnd::condition_generator] objects are not conditions. You may have made this mistake:"
#> [86] "#'"
#> [87] "#' ```r"
#> [88] "#' x <- condition(\"my_condition\")"
#> [89] "#' conditionMessage(x)"
#> [90] "#' ```"
#> [91] "#'"
#> [92] "#' Condition generators need to be called first before they can be used as conditions. Try this instead:"
#> [93] "#'"
#> [94] "#' ```r"
#> [95] "#' x <- condition(\"my_condition\")"
#> [96] "#' conditionMessage(x())"
#> [97] "#' ```"
#> [98] "#' }"
#> [99] "#' \\subsection{`cnd:condition_overwrite/warning`}{"
#> [100] "#' \\describe{"
#> [101] "#' \\item{package}{`{cnd}`}"
#> [102] "#' \\item{class}{`cnd:condition_overwrite`}"
#> [103] "#' \\item{type}{**warning**}"
#> [104] "#' }"
#> [105] "#' Defining a new condition with the same class and package as an existing condition will overwrite the previous definition. It is recommended to either avoid this by fully defining your condition, or creating a new condition instead."
#> [106] "#' }"
#> [107] "#' \\subsection{`cnd:conditions_dots/warning`}{"
#> [108] "#' \\describe{"
#> [109] "#' \\item{package}{`{cnd}`}"
#> [110] "#' \\item{class}{`cnd:conditions_dots`}"
#> [111] "#' \\item{type}{**warning**}"
#> [112] "#' }"
#> [113] "#' The `...` parameter in [cnd::conditions()] is meant for convenience. Only a single argument is allowed. Other parameters must be named explicitly."
#> [114] "#'"
#> [115] "#' For example:"
#> [116] "#'"
#> [117] "#' ```r"
#> [118] "#' # Instead of this"
#> [119] "#' conditions(\"class\", \"package\") # \"package\" is ignored with a warning"
#> [120] "#'"
#> [121] "#' # Do this"
#> [122] "#' conditions(class = \"class\", package = \"package\")"
#> [123] "#' ```"
#> [124] "#' }"
#> [125] "#' \\subsection{`cnd:invalid_condition/error`}{"
#> [126] "#' \\describe{"
#> [127] "#' \\item{package}{`{cnd}`}"
#> [128] "#' \\item{class}{`cnd:invalid_condition`}"
#> [129] "#' \\item{type}{**error**}"
#> [130] "#' }"
#> [131] "#' The `class`, `exports`, and `help` parameters must be a single character string. If you are passing a function, it must be a valid function."
#> [132] "#' }"
#> [133] "#' \\subsection{`cnd:invalid_condition_message/error`}{"
#> [134] "#' \\describe{"
#> [135] "#' \\item{package}{`{cnd}`}"
#> [136] "#' \\item{class}{`cnd:invalid_condition_message`}"
#> [137] "#' \\item{type}{**error**}"
#> [138] "#' }"
#> [139] "#' Conditions messages are displayed when invoked through [conditionMessage()]. You can set a static message by passing through a `character` vector, or a dynamic message by passing through a `function`. The function should return a `character` vector."
#> [140] "#'"
#> [141] "#' When `message` is not set, a default \"there was an error\" message is used."
#> [142] "#' }"
#> [143] "#' \\subsection{`cnd:match_arg/error`}{"
#> [144] "#' \\describe{"
#> [145] "#' \\item{package}{`{cnd}`}"
#> [146] "#' \\item{class}{`cnd:match_arg`}"
#> [147] "#' \\item{type}{**error**}"
#> [148] "#' }"
#> [149] "#' Mostly [match.arg()] but with a custom condition"
#> [150] "#' }"
#> [151] "#' \\subsection{`cnd:no_package_exports/warning`}{"
#> [152] "#' \\describe{"
#> [153] "#' \\item{package}{`{cnd}`}"
#> [154] "#' \\item{class}{`cnd:no_package_exports`}"
#> [155] "#' \\item{type}{**warning**}"
#> [156] "#' }"
#> [157] "#' The `exports` parameter requires a `package`"
#> [158] "#' }"
#> [159] "#'"
#> [160] "#' @seealso [cnd::cnd-package] [cnd::condition]"
#> [161] "#' @keywords internal"
#> [162] "#'"
#> [163] "NULL"
cnd_section("cnd")
#> [1] "\nConditions are generated through the [`{cnd}`][cnd::cnd-package] package.\nThe following conditions are associated with this function:\n\n\\describe{\n \n \\item{[`\033[1mcnd\033[22m:cond_cnd_class/\033[31merror\033[39m`][cnd-cnd-conditions]}{\n [cnd::cnd()] simple calls the appropriate function: [stop()], [warning()], or [message()] based on the `type` parameter from [cnd::condition()].\n }\n\n}\n\nFor more conditions, see: [cnd-cnd-conditions]\n"