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