nixos/doc: clean up defaults and examples

2 files changed, 29 insertions, 1 deletions

diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md
index 819c23684cdf7..be56529992ab1 100644
--- a/nixos/doc/manual/development/option-declarations.section.md
+++ b/nixos/doc/manual/development/option-declarations.section.md
@@ -38,9 +38,19 @@ The function `mkOption` accepts the following arguments.
     of the module will have to define the value of the option, otherwise
     an error will be thrown.
 
+`defaultText`
+
+:   A textual representation of the default value to be rendered verbatim in
+    the manual. Useful if the default value is a complex expression or depends
+    on other values or packages.
+    Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for
+    a plain English description in DocBook format.
+
 `example`
 
 :   An example value that will be shown in the NixOS manual.
+    You can use `lib.literalExpression` and `lib.literalDocBook` in the same way
+    as in `defaultText`.
 
 `description`
 
diff --git a/nixos/doc/manual/from_md/development/option-declarations.section.xml b/nixos/doc/manual/from_md/development/option-declarations.section.xml
index 85a59a543d14e..2845e37659b1b 100644
--- a/nixos/doc/manual/from_md/development/option-declarations.section.xml
+++ b/nixos/doc/manual/from_md/development/option-declarations.section.xml
@@ -59,11 +59,29 @@ options = {
     </varlistentry>
     <varlistentry>
       <term>
+        <literal>defaultText</literal>
+      </term>
+      <listitem>
+        <para>
+          A textual representation of the default value to be rendered
+          verbatim in the manual. Useful if the default value is a
+          complex expression or depends on other values or packages. Use
+          <literal>lib.literalExpression</literal> for a Nix expression,
+          <literal>lib.literalDocBook</literal> for a plain English
+          description in DocBook format.
+        </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>
         <literal>example</literal>
       </term>
       <listitem>
         <para>
-          An example value that will be shown in the NixOS manual.
+          An example value that will be shown in the NixOS manual. You
+          can use <literal>lib.literalExpression</literal> and
+          <literal>lib.literalDocBook</literal> in the same way as in
+          <literal>defaultText</literal>.
         </para>
       </listitem>
     </varlistentry>