public
/
nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

manual: reworked submodule section for better readability 

The section was strange to read, as the initial example already used
`listOf' which is mentioned in the very first paragraph. Then you read
in a subsection about `listOf' and the exact same example is given
once again.
This commit is contained in:
Thomas Bach 2017-09-10 08:50:07 +08:00 committed by Domen Kožar
parent f37a1e155e
commit 4d101993bf
1 changed files with 30 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
nixos/doc/manual/development/option-types.xml
View File

@ -157,26 +157,26 @@
<section xml:id='section-option-types-submodule'><title>Submodule</title> <section xml:id='section-option-types-submodule'><title>Submodule</title>
<para>Submodule is a very powerful type that defines a set of sub-options that <para><literal>submodule</literal> is a very powerful type that defines a set
are handled like a separate module. of sub-options that are handled like a separate module.</para>
It is especially interesting when used with composed types like
<literal>attrsOf</literal> or <literal>listOf</literal>.</para>
<para>The submodule type take a parameter <replaceable>o</replaceable>, that <para>It takes a parameter <replaceable>o</replaceable>, that should be a set,
should be a set, or a function returning a set with an or a function returning a set with an <literal>options</literal> key
<literal>options</literal> key defining the sub-options. defining the sub-options.
The option set can be defined directly (<xref linkend='ex-submodule-direct' Submodule option definitions are type-checked accordingly to the
/>) or as reference (<xref linkend='ex-submodule-reference' />).</para> <literal>options</literal> declarations.
Of course, you can nest submodule option definitons for even higher
modularity.</para>
<para>Submodule option definitions are type-checked accordingly to the options <para>The option set can be defined directly
declarations. It is possible to declare submodule options inside a submodule (<xref linkend='ex-submodule-direct' />) or as reference
sub-options for even higher modularity.</para> (<xref linkend='ex-submodule-reference' />).</para>
<example xml:id='ex-submodule-direct'><title>Directly defined submodule</title> <example xml:id='ex-submodule-direct'><title>Directly defined submodule</title>
<screen> <screen>
options.mod = mkOption { options.mod = mkOption {
description = "submodule example"; description = "submodule example";
type = with types; listOf (submodule { type = with types; submodule {
options = { options = {
foo = mkOption { foo = mkOption {
type = int; type = int;
@ -185,7 +185,7 @@ options.mod = mkOption {
type = str; type = str;
}; };
}; };
}); };
};</screen></example> };</screen></example>
<example xml:id='ex-submodule-reference'><title>Submodule defined as a <example xml:id='ex-submodule-reference'><title>Submodule defined as a
@ -205,16 +205,20 @@ let
in in
options.mod = mkOption { options.mod = mkOption {
description = "submodule example"; description = "submodule example";
type = with types; listOf (submodule modOptions); type = with types; submodule modOptions;
};</screen></example> };</screen></example>
<section><title>Composed with <literal>listOf</literal></title> <para>The <literal>submodule</literal> type is especially interesting when
used with composed types like <literal>attrsOf</literal> or
<literal>listOf</literal>.
When composed with <literal>listOf</literal>
(<xref linkend='ex-submodule-listof-declaration' />),
<literal>submodule</literal> allows multiple definitions of the submodule
option set (<xref linkend='ex-submodule-listof-definition' />).</para>
<para>When composed with <literal>listOf</literal>, submodule allows multiple
definitions of the submodule option set.</para>
<example xml:id='ex-submodule-listof-declaration'><title>Declaration of a list <example xml:id='ex-submodule-listof-declaration'><title>Declaration of a list
of submodules</title> nof submodules</title>
<screen> <screen>
options.mod = mkOption { options.mod = mkOption {
description = "submodule example"; description = "submodule example";
@ -238,13 +242,11 @@ config.mod = [
{ foo = 2; bar = "two"; } { foo = 2; bar = "two"; }
];</screen></example> ];</screen></example>
</section> <para>When composed with <literal>attrsOf</literal>
(<xref linkend='ex-submodule-attrsof-declaration' />),
<literal>submodule</literal> allows multiple named definitions of the
<section><title>Composed with <literal>attrsOf</literal></title> submodule option set (<xref linkend='ex-submodule-attrsof-definition' />).
</para>
<para>When composed with <literal>attrsOf</literal>, submodule allows multiple
named definitions of the submodule option set.</para>
<example xml:id='ex-submodule-attrsof-declaration'><title>Declaration of <example xml:id='ex-submodule-attrsof-declaration'><title>Declaration of
attribute sets of submodules</title> attribute sets of submodules</title>
@ -269,7 +271,6 @@ options.mod = mkOption {
config.mod.one = { foo = 1; bar = "one"; }; config.mod.one = { foo = 1; bar = "one"; };
config.mod.two = { foo = 2; bar = "two"; };</screen></example> config.mod.two = { foo = 2; bar = "two"; };</screen></example>
</section>
</section> </section>
<section><title>Extending types</title> <section><title>Extending types</title>