nixos/doc: document `mkOrder` and friends

Add a section on ordering option definitions.

Also mention `mkDefault` in the section on `mkOverride`.

Clarify the code a bit by renaming `defaultPriority` to
`defaultOverridePriority` and introducing `defaultOrderPriority`.

2 files changed, 56 insertions, 10 deletions

diff --git a/nixos/doc/manual/development/option-def.section.md b/nixos/doc/manual/development/option-def.section.md
index 91b24cd4a3a16..22cf38873cf07 100644
--- a/nixos/doc/manual/development/option-def.section.md
+++ b/nixos/doc/manual/development/option-def.section.md
@@ -59,17 +59,35 @@ config = {
 ## Setting Priorities {#sec-option-definitions-setting-priorities .unnumbered}
 
 A module can override the definitions of an option in other modules by
-setting a *priority*. All option definitions that do not have the lowest
+setting an *override priority*. All option definitions that do not have the lowest
 priority value are discarded. By default, option definitions have
-priority 1000. You can specify an explicit priority by using
-`mkOverride`, e.g.
+priority 100 and option defaults have priority 1500.
+You can specify an explicit priority by using `mkOverride`, e.g.
 
 ```nix
 services.openssh.enable = mkOverride 10 false;
 ```
 
 This definition causes all other definitions with priorities above 10 to
-be discarded. The function `mkForce` is equal to `mkOverride 50`.
+be discarded. The function `mkForce` is equal to `mkOverride 50`, and
+`mkDefault` is equal to `mkOverride 1000`.
+
+## Ordering Definitions {#sec-option-definitions-ordering .unnumbered}
+
+It is also possible to influence the order in which the definitions for an option are
+merged by setting an *order priority* with `mkOrder`. The default order priority is 1000.
+The functions `mkBefore` and `mkAfter` are equal to `mkOrder 500` and `mkOrder 1500`, respectively.
+As an example,
+
+```nix
+hardware.firmware = mkBefore [ myFirmware ];
+```
+
+This definition ensures that `myFirmware` comes before other unordered
+definitions in the final list value of `hardware.firmware`.
+
+Note that this is different from [override priorities](#sec-option-definitions-setting-priorities):
+setting an order does not affect whether the definition is included or not.
 
 ## Merging Configurations {#sec-option-definitions-merging .unnumbered}
 
diff --git a/nixos/doc/manual/from_md/development/option-def.section.xml b/nixos/doc/manual/from_md/development/option-def.section.xml
index 8c9ef181affd2..3c1a979e70f33 100644
--- a/nixos/doc/manual/from_md/development/option-def.section.xml
+++ b/nixos/doc/manual/from_md/development/option-def.section.xml
@@ -66,11 +66,11 @@ config = {
     <title>Setting Priorities</title>
     <para>
       A module can override the definitions of an option in other
-      modules by setting a <emphasis>priority</emphasis>. All option
-      definitions that do not have the lowest priority value are
-      discarded. By default, option definitions have priority 1000. You
-      can specify an explicit priority by using
-      <literal>mkOverride</literal>, e.g.
+      modules by setting an <emphasis>override priority</emphasis>. All
+      option definitions that do not have the lowest priority value are
+      discarded. By default, option definitions have priority 100 and
+      option defaults have priority 1500. You can specify an explicit
+      priority by using <literal>mkOverride</literal>, e.g.
     </para>
     <programlisting language="bash">
 services.openssh.enable = mkOverride 10 false;
@@ -78,7 +78,35 @@ services.openssh.enable = mkOverride 10 false;
     <para>
       This definition causes all other definitions with priorities above
       10 to be discarded. The function <literal>mkForce</literal> is
-      equal to <literal>mkOverride 50</literal>.
+      equal to <literal>mkOverride 50</literal>, and
+      <literal>mkDefault</literal> is equal to
+      <literal>mkOverride 1000</literal>.
+    </para>
+  </section>
+  <section xml:id="sec-option-definitions-ordering">
+    <title>Ordering Definitions</title>
+    <para>
+      It is also possible to influence the order in which the
+      definitions for an option are merged by setting an <emphasis>order
+      priority</emphasis> with <literal>mkOrder</literal>. The default
+      order priority is 1000. The functions <literal>mkBefore</literal>
+      and <literal>mkAfter</literal> are equal to
+      <literal>mkOrder 500</literal> and
+      <literal>mkOrder 1500</literal>, respectively. As an example,
+    </para>
+    <programlisting language="bash">
+hardware.firmware = mkBefore [ myFirmware ];
+</programlisting>
+    <para>
+      This definition ensures that <literal>myFirmware</literal> comes
+      before other unordered definitions in the final list value of
+      <literal>hardware.firmware</literal>.
+    </para>
+    <para>
+      Note that this is different from
+      <link linkend="sec-option-definitions-setting-priorities">override
+      priorities</link>: setting an order does not affect whether the
+      definition is included or not.
     </para>
   </section>
   <section xml:id="sec-option-definitions-merging">