alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

lib/options: Update documentation comments for docs generation

Browse source 
Documents functions in `lib.options` for docs generation with nixdoc.

The formatting change in the `mkOption` arguments is due to the way
`nixdoc` parses documentation comments on pattern arguments. It's not
ideal, but it works.
This commit is contained in:
Vincent Ambo 2018-10-28 21:31:35 +01:00
parent da18b92635
commit 2384966880
1 changed files with 88 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

153
lib/options.nix
View file

@ -8,61 +8,72 @@ with lib.strings;
rec { rec {
# Returns true when the given argument is an option /* Returns true when the given argument is an option
#
# Examples: Type: isOption :: a -> bool
# isOption 1 // => false
# isOption (mkOption {}) // => true Example:
isOption 1 // => false
isOption (mkOption {}) // => true
*/
isOption = lib.isType "option"; isOption = lib.isType "option";
# Creates an Option attribute set. mkOption accepts an attribute set with the following keys: /* Creates an Option attribute set. mkOption accepts an attribute set with the following keys:
#
# default: Default value used when no definition is given in the configuration. All keys default to `null` when not given.
# defaultText: Textual representation of the default, for in the manual.
# example: Example value used in the manual. Example:
# description: String describing the option. mkOption { } // => { _type = "option"; }
# type: Option type, providing type-checking and value merging. mkOption { defaultText = "foo"; } // => { _type = "option"; defaultText = "foo"; }
# apply: Function that converts the option value to something else. */
# internal: Whether the option is for NixOS developers only.
# visible: Whether the option shows up in the manual.
# readOnly: Whether the option can be set only once
# options: Obsolete, used by types.optionSet.
#
# All keys default to `null` when not given.
#
# Examples:
# mkOption { } // => { _type = "option"; }
# mkOption { defaultText = "foo"; } // => { _type = "option"; defaultText = "foo"; }
mkOption = mkOption =
{ default ? null # Default value used when no definition is given in the configuration. {
, defaultText ? null # Textual representation of the default, for in the manual. # Default value used when no definition is given in the configuration.
, example ? null # Example value used in the manual. default ? null,
, description ? null # String describing the option. # Textual representation of the default, for the manual.
, relatedPackages ? null # Related packages used in the manual (see `genRelatedPackages` in ../nixos/doc/manual/default.nix). defaultText ? null,
, type ? null # Option type, providing type-checking and value merging. # Example value used in the manual.
, apply ? null # Function that converts the option value to something else. example ? null,
, internal ? null # Whether the option is for NixOS developers only. # String describing the option.
, visible ? null # Whether the option shows up in the manual. description ? null,
, readOnly ? null # Whether the option can be set only once # Related packages used in the manual (see `genRelatedPackages` in ../nixos/doc/manual/default.nix).
, options ? null # Obsolete, used by types.optionSet. relatedPackages ? null,
# Option type, providing type-checking and value merging.
type ? null,
# Function that converts the option value to something else.
apply ? null,
# Whether the option is for NixOS developers only.
internal ? null,
# Whether the option shows up in the manual.
visible ? null,
# Whether the option can be set only once
readOnly ? null,
# Obsolete, used by types.optionSet.
options ? null
} @ attrs: } @ attrs:
attrs // { _type = "option"; }; attrs // { _type = "option"; };
# Creates a Option attribute set for a boolean value option i.e an option to be toggled on or off: /* Creates an Option attribute set for a boolean value option i.e an
# option to be toggled on or off:
# Examples:
# mkEnableOption "foo" // => { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; } Example:
mkEnableOption = name: mkOption { mkEnableOption "foo"
=> { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }
*/
mkEnableOption =
# Name for the created option
name: mkOption {
default = false; default = false;
example = true; example = true;
description = "Whether to enable ${name}."; description = "Whether to enable ${name}.";
type = lib.types.bool; type = lib.types.bool;
}; };
# This option accept anything, but it does not produce any result. This /* This option accepts anything, but it does not produce any result.
# is useful for sharing a module across different module sets without
# having to implement similar features as long as the value of the options This is useful for sharing a module across different module sets
# are not expected. without having to implement similar features as long as the
values of the options are not accessed. */
mkSinkUndeclaredOptions = attrs: mkOption ({ mkSinkUndeclaredOptions = attrs: mkOption ({
internal = true; internal = true;
visible = false; visible = false;
@ -102,18 +113,24 @@ rec {
else else
val) (head defs).value defs; val) (head defs).value defs;
# Extracts values of all "value" keys of the given list /* Extracts values of all "value" keys of the given list.
#
# Examples: Type: getValues :: [ { value :: a } ] -> [a]
# getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
# getValues [ ] // => [ ] Example:
getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
getValues [ ] // => [ ]
*/
getValues = map (x: x.value); getValues = map (x: x.value);
# Extracts values of all "file" keys of the given list /* Extracts values of all "file" keys of the given list
#
# Examples: Type: getFiles :: [ { file :: a } ] -> [a]
# getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
# getFiles [ ] // => [ ] Example:
getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
getFiles [ ] // => [ ]
*/
getFiles = map (x: x.file); getFiles = map (x: x.file);
# Generate documentation template from the list of option declaration like # Generate documentation template from the list of option declaration like
@ -146,10 +163,13 @@ rec {
/* This function recursively removes all derivation attributes from /* This function recursively removes all derivation attributes from
`x' except for the `name' attribute. This is to make the `x` except for the `name` attribute.
generation of `options.xml' much more efficient: the XML
representation of derivations is very large (on the order of This is to make the generation of `options.xml` much more
megabytes) and is not actually used by the manual generator. */ efficient: the XML representation of derivations is very large
(on the order of megabytes) and is not actually used by the
manual generator.
*/
scrubOptionValue = x: scrubOptionValue = x:
if isDerivation x then if isDerivation x then
{ type = "derivation"; drvPath = x.name; outPath = x.name; name = x.name; } { type = "derivation"; drvPath = x.name; outPath = x.name; name = x.name; }
@ -158,20 +178,21 @@ rec {
else x; else x;
/* For use in the ‘example’ option attribute. It causes the given /* For use in the `example` option attribute. It causes the given
text to be included verbatim in documentation. This is necessary text to be included verbatim in documentation. This is necessary
for example values that are not simple values, e.g., for example values that are not simple values, e.g., functions.
functions. */ */
literalExample = text: { _type = "literalExample"; inherit text; }; literalExample = text: { _type = "literalExample"; inherit text; };
# Helper functions.
/* Helper functions. */ /* Convert an option, described as a list of the option parts in to a
safe, human readable version.
# Convert an option, described as a list of the option parts in to a Example:
# safe, human readable version. ie: (showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
# (showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
# (showOption ["foo" "bar" "baz"]) == "foo.bar.baz" */
# (showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
showOption = parts: let showOption = parts: let
escapeOptionPart = part: escapeOptionPart = part:
let let