Cleaner documentation. (#91)

No luck setting up a catch-all, but it should be easier to keep things organized now.

R/absolute_paths.R

@@ -13,6 +13,7 @@ NULL
 #' @return A `rapid` object as returned by [class_rapid()], with absolute server
 #'   paths.
 #' @export
+#' @family rapid
 expand_servers <- S7::new_generic("expand_servers", "x")
 
 S7::method(expand_servers, class_rapid) <- function(x) {

R/as.R

@@ -15,6 +15,7 @@
 #'
 #' @return An object with the specified `target_class`.
 #' @export
+#' @family rapid
 as_api_object <- S7::new_generic(
   "as_api_object",
   "x",

R/components-reference.R

@@ -22,8 +22,8 @@ NULL
 #' @return A `reference` S7 object pointing (by name) to another part of the
 #'   `rapid` object.
 #' @export
-#'
-#' @seealso [as_reference()] for coercing objects to `reference`.
+#' @family components_reference
+#' @family components
 #'
 #' @examples
 #' class_reference("#/components/schemas/Pet")
@@ -63,6 +63,8 @@ S7::method(length, class_reference) <- function(x) {
 #'
 #' @return A `reference` as returned by [class_reference()].
 #' @export
+#' @family components_reference
+#' @family components
 #'
 #' @examples
 #' as_reference()

R/components-schema.R

@@ -22,8 +22,8 @@ NULL
 #' @return A `schema` S7 object describing the data type, with fields `type`,
 #'   `nullable`, `description`, and `format`.
 #' @export
-#'
-#' @seealso [as_schema()] for coercing objects to `schema`.
+#' @family components_schema
+#' @family components
 #'
 #' @examples
 #' class_schema("string")
@@ -90,6 +90,8 @@ S7::method(length, class_schema) <- function(x) {
 #'
 #' @return A `schema` as returned by [class_schema()].
 #' @export
+#' @family components_schema
+#' @family components
 #'
 #' @examples
 #' as_schema()

R/components-security_scheme-api_key.R

@@ -14,6 +14,8 @@ NULL
 #' @return An `api_key_security_scheme` S7 object, with fields `parameter_name`
 #'   and `location`.
 #' @export
+#' @family components_security_schemes
+#' @family components
 #'
 #' @examples
 #' class_api_key_security_scheme(
@@ -71,6 +73,8 @@ S7::method(length, class_api_key_security_scheme) <- function(x) {
 #' @return An `api_key_security_scheme` as returned by
 #'   [class_api_key_security_scheme()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 as_api_key_security_scheme <- function(x,
                                        ...,
                                        arg = caller_arg(x),

R/components-security_scheme-oauth2-authorization_code_flow.R

@@ -12,7 +12,12 @@ NULL
 #' @inheritParams class_oauth2_implicit_flow
 #' @inheritParams class_oauth2_token_flow
 #'
+#' @return An `oauth2_authorization_code_flow` S7 object, with fields
+#'   `authorization_url`, `token_url`, `refresh_url`, and `scopes`.
 #' @export
+#' @family components_security_schemes
+#' @family components
+#'
 #' @examples
 #' class_oauth2_authorization_code_flow(
 #'   authorization_url = "https://example.com/authorize",
@@ -77,6 +82,8 @@ S7::method(length, class_oauth2_authorization_code_flow) <- function(x) {
 #' @return An `oauth2_authorization_code_flow` as returned by
 #'   [class_oauth2_authorization_code_flow()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 as_oauth2_authorization_code_flow <- function(x,
                                               ...,
                                               arg = caller_arg(x),

R/components-security_scheme-oauth2-implicit_flow.R

@@ -12,7 +12,12 @@ NULL
 #'   to be used for this flow. This must be in the form of a URL. The OAuth2
 #'   standard requires the use of TLS.
 #'
+#' @return An `oauth2_implicit_flow` S7 object, with fields `authorization_url`,
+#'   `refresh_url`, and `scopes`.
 #' @export
+#' @family components_security_schemes
+#' @family components
+#'
 #' @examples
 #' class_oauth2_implicit_flow(
 #'   authorization_url = "https://example.com/authorize",
@@ -68,6 +73,8 @@ S7::method(length, class_oauth2_implicit_flow) <- function(x) {
 #' @return An `oauth2_implicit_flow` as returned by
 #'   [class_oauth2_implicit_flow()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 as_oauth2_implicit_flow <- function(x,
                                     ...,
                                     arg = caller_arg(x),

R/components-security_scheme-oauth2-scopes.R

@@ -7,8 +7,10 @@
 #'   scope.
 #'
 #' @return A `scopes` S7 object, with fields `name` and `description`.
-#' @seealso [as_scopes()] for coercing objects to `scopes`.
 #' @export
+#' @family components_security_schemes
+#' @family components
+#'
 #' @examples
 #' class_scopes(
 #'   name = c(
@@ -69,6 +71,8 @@ S7::method(length, class_scopes) <- function(x) {
 #'
 #' @return A `scopes` as returned by [class_scopes()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 as_scopes <- S7::new_generic("as_scopes", "x")
 
 S7::method(

R/components-security_scheme-oauth2-token_flow.R

@@ -13,9 +13,12 @@ NULL
 #'   this flow. This must be in the form of a URL. The OAuth2 standard requires
 #'   the use of TLS.
 #'
-#' @return An `oauth2_token_flow` object.
-#'
+#' @return An `oauth2_token_flow` S7 object, with fields `token_url`,
+#'   `refresh_url`, and `scopes`.
 #' @export
+#' @family components_security_schemes
+#' @family components
+#'
 #' @examples
 #' class_oauth2_token_flow(
 #'   token_url = "https://example.com/token",
@@ -73,6 +76,8 @@ S7::method(length, class_oauth2_token_flow) <- function(x) {
 #'
 #' @return An `oauth2_token_flow` as returned by [class_oauth2_token_flow()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 as_oauth2_token_flow <- function(x,
                                  ...,
                                  arg = caller_arg(x),

R/components-security_scheme-oauth2.R

@@ -19,6 +19,8 @@ NULL
 #' @return An `oauth2_security_scheme` S7 object, with fields `implicit_flow`,
 #'   `password_flow`, `client_credentials_flow`, and `authorization_code_flow`.
 #' @export
+#' @family components_security_schemes
+#' @family components
 #'
 #' @examples
 #' class_oauth2_security_scheme()
@@ -73,6 +75,8 @@ S7::method(length, class_oauth2_security_scheme) <- function(x) {
 #' @return An `oauth2_security_scheme` as returned by
 #'   [class_oauth2_security_scheme()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 as_oauth2_security_scheme <- S7::new_generic("as_oauth2_security_scheme", "x")
 
 S7::method(

R/components-security_scheme.R

@@ -27,6 +27,8 @@ abstract_security_scheme <- S7::new_class(
 #' @return A `security_scheme` object as returned by
 #'   [class_api_key_security_scheme()] or [class_oauth2_security_scheme()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 #'
 #' @examples
 #' as_security_scheme(

R/components-security_scheme_details.R

@@ -12,6 +12,8 @@
 #' @return A `security_scheme_details` object, which is a validated list of
 #'   [abstract_security_scheme()] objects.
 #' @export
+#' @family components_security_schemes
+#' @family components
 #'
 #' @examples
 #' class_security_scheme_details(
@@ -90,6 +92,8 @@ class_security_scheme_details <- S7::new_class(
 #' @return A `security_scheme_details` object as returned by
 #'   [class_security_scheme_details()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 #'
 #' @examples
 #' as_security_scheme_details()

R/components-security_schemes.R

@@ -19,6 +19,9 @@ NULL
 #' @return A `security_schemes` S7 object with details about security available
 #'   for operations.
 #' @export
+#' @family components_security_schemes
+#' @family components
+#'
 #' @examples
 #' class_security_schemes()
 #' class_security_schemes(
@@ -96,6 +99,8 @@ S7::method(length, class_security_schemes) <- function(x) {
 #' @return A `security_schemes` object as returned by
 #'   [class_security_schemes()].
 #' @export
+#' @family components_security_schemes
+#' @family components
 #'
 #' @examples
 #' as_security_schemes()

R/components.R

@@ -15,9 +15,9 @@ NULL
 #'
 #' @return A `components` S7 object with various schemas for the API.
 #' @export
-#'
 #' @seealso [as_components()] for coercing objects to
 #'   `components` objects.
+#' @family components
 #'
 #' @examples
 #' class_components()
@@ -66,6 +66,8 @@ S7::method(length, class_components) <- function(x) {
 #' @return A `components` object as returned by
 #'   [class_components()].
 #' @export
+#' @seealso [class_components()] for creating `components` objects.
+#' @family components
 #'
 #' @examples
 #' as_components()

R/info-contact.R

@@ -15,8 +15,7 @@ NULL
 #' @return A `contact` S7 object describing who to contact for information about
 #'   the API, with fields `name`, `email`, and `url`.
 #' @export
-#'
-#' @seealso [as_contact()] for coercing objects to `contact`.
+#' @family info
 #'
 #' @examples
 #' class_contact(
@@ -55,6 +54,7 @@ S7::method(length, class_contact) <- function(x) {
 #'
 #' @return A `contact` as returned by [class_contact()].
 #' @export
+#' @family info
 #'
 #' @examples
 #' as_contact()

R/info-license.R

@@ -19,8 +19,7 @@ NULL
 #' @return A `license` S7 object describing allowed usage of the API, with
 #'   fields `name`, `identifier`, and `url`.
 #' @export
-#'
-#' @seealso [as_license()] for coercing objects to `license`.
+#' @family info
 #'
 #' @examples
 #' class_license(
@@ -77,6 +76,7 @@ S7::method(length, class_license) <- function(x) {
 #'
 #' @return A `license` as returned by [class_license()].
 #' @export
+#' @family info
 #'
 #' @examples
 #' as_license()

R/info-origin.R

@@ -20,8 +20,7 @@ NULL
 #' @return An `origin` S7 object describing where to find the API description,
 #'   with fields `url`, `format`, and `version`.
 #' @export
-#'
-#' @seealso [as_origin()] for coercing objects to `origin`.
+#' @family info
 #'
 #' @examples
 #' class_origin(
@@ -76,6 +75,7 @@ S7::method(length, class_origin) <- function(x) {
 #'
 #' @return An `origin` as returned by [class_origin()].
 #' @export
+#' @family info
 #'
 #' @examples
 #' as_origin()

R/info.R

@@ -33,8 +33,7 @@ NULL
 #'
 #' @return An `info` S7 object with metadata describing a single API.
 #' @export
-#'
-#' @seealso [as_info()] for coercing objects to `info`.
+#' @family info
 #'
 #' @examples
 #' class_info()
@@ -124,6 +123,7 @@ S7::method(length, class_info) <- function(x) {
 #'
 #' @return An `info` object as returned by [class_info()].
 #' @export
+#' @family info
 #'
 #' @examples
 #' as_info()

R/paths.R

@@ -8,8 +8,7 @@
 #'
 #' @return A `paths` S7 object with details about API endpoints.
 #' @export
-#'
-#' @seealso [as_paths()] for coercing objects to `paths`.
+#' @family paths
 #'
 #' @examples
 #' class_paths()
@@ -48,6 +47,7 @@ class_paths <- S7::new_class(
 #'
 #' @return A `paths` object as returned by [class_paths()].
 #' @export
+#' @family paths
 #'
 #' @examples
 #' as_paths()

R/security.R

@@ -17,6 +17,8 @@ NULL
 #' @return A `security` S7 object with references of security required for
 #'   operations.
 #' @export
+#' @family security
+#'
 #' @examples
 #' class_security()
 #' class_security(
@@ -76,6 +78,7 @@ S7::method(length, class_security) <- function(x) {
 #'
 #' @return A `security` object as returned by [class_security()].
 #' @export
+#' @family security
 #'
 #' @examples
 #' as_security()

R/servers-server_variables.R

@@ -9,8 +9,7 @@
 #' @return A `server_variables` S7 object, which is a validated list of
 #'   [class_string_replacements()] objects.
 #' @export
-#'
-#' @seealso [as_server_variables()] for coercing objects to `server_variables`.
+#' @family servers
 #'
 #' @examples
 #' class_server_variables(
@@ -57,6 +56,7 @@ class_server_variables <- S7::new_class(
 #' @return A `server_variables` object as returned by
 #'   [class_server_variables()].
 #' @export
+#' @family servers
 #'
 #' @examples
 #' as_server_variables()

R/servers-string_replacements.R

@@ -25,10 +25,7 @@ NULL
 #'   variables for a single server, with fields `name`, `default`, `enum`, and
 #'   `description`.
 #' @export
-#'
-#' @seealso [as_string_replacements()] for coercing objects to
-#'   `string_replacements`, and [class_server_variables()] for creating
-#'   collections of `string_replacements`.
+#' @family servers
 #'
 #' @examples
 #' class_string_replacements(
@@ -94,6 +91,7 @@ S7::method(length, class_string_replacements) <- function(x) {
 #'
 #' @return A `string_replacements` as returned by [class_string_replacements()].
 #' @export
+#' @family servers
 #'
 #' @examples
 #' as_string_replacements()