docs, dconf: GVariant documentation improvements

PR #3956

docs/writing-modules.adoc

@@ -7,7 +7,7 @@ The module system in Home Manager is based entirely on the NixOS module system s
 [[sec-option-types]]
 === Option Types
 :wikipedia-dag: https://en.wikipedia.org/w/index.php?title=Directed_acyclic_graph&oldid=939656095
-:gvariant-description: https://developer.gnome.org/glib/stable/glib-GVariant.html#glib-GVariant.description
+:gvariant-description: https://docs.gtk.org/glib/struct.Variant.html#description
 
 Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types `dagOf` and `gvariant` that are used, for example, by <<opt-programs.ssh.matchBlocks>> and <<opt-dconf.settings>>.
 
@@ -77,13 +77,13 @@ foo.bar = {
 +
 would place `c` before `b` and after `a` in the graph.
 
-`hm.types.gvariant`::
-This type is useful for options representing {gvariant-description}[GVariant] values. The type accepts all primitive GVariant types as well as arrays and tuples. Dictionaries are not currently supported.
+[[sec-option-types-gvariant]]`hm.types.gvariant`::
+This type is useful for options representing {gvariant-description}[GVariant] values. The type accepts all primitive GVariant types as well as arrays, tuples, ``maybe'' types, and dictionaries.
 +
-To create a GVariant value you can use a number of provided functions. Examples assume an option `foo.bar`  of type `hm.types.gvariant`.
+Some Nix values are automatically coerced to matching GVariant value but the GVariant model is richer so you may need to use one of the provided constructor functions. Examples assume an option `foo.bar`  of type `hm.types.gvariant`.
 +
-`hm.gvariant.mkBoolean (v: bool)`:::
-Takes a Nix value `v` to a GVariant `boolean` value. Note, Nix booleans are automatically coerced using this function. That is,
+[[sec-option-types-gvariant-mkBoolean]]`hm.gvariant.mkBoolean (v: bool)`:::
+Takes a Nix value `v` to a GVariant `boolean` value (GVariant format string `b`). Note, Nix booleans are automatically coerced using this function. That is,
 +
 [source,nix]
 ----
@@ -96,8 +96,8 @@ is equivalent to
 ----
 foo.bar = true;
 ----
-`hm.gvariant.mkString (v: string)`:::
-Takes a Nix value `v` to a GVariant `string` value. Note, Nix strings are automatically coerced using this function. That is,
+[[sec-option-types-gvariant-mkString]]`hm.gvariant.mkString (v: string)`:::
+Takes a Nix value `v` to a GVariant `string` value (GVariant format string `s`). Note, Nix strings are automatically coerced using this function. That is,
 +
 [source,nix]
 ----
@@ -110,16 +110,16 @@ is equivalent to
 ----
 foo.bar = "a string";
 ----
-`hm.gvariant.mkObjectpath (v: string)`:::
-Takes a Nix value `v` to a GVariant `objectpath` value.
-`hm.gvariant.mkUchar (v: string)`:::
-Takes a Nix value `v` to a GVariant `uchar` value.
-`hm.gvariant.mkInt16 (v: int)`:::
-Takes a Nix value `v` to a GVariant `int16` value.
-`hm.gvariant.mkUint16 (v: int)`:::
-Takes a Nix value `v` to a GVariant `uint16` value.
-`hm.gvariant.mkInt32 (v: int)`:::
-Takes a Nix value `v` to a GVariant `int32` value. Note, Nix integers are automatically coerced using this function. That is,
+[[sec-option-types-gvariant-mkObjectpath]]`hm.gvariant.mkObjectpath (v: string)`:::
+Takes a Nix value `v` to a GVariant `objectpath` value (GVariant format string `o`).
+[[sec-option-types-gvariant-mkUchar]]`hm.gvariant.mkUchar (v: string)`:::
+Takes a Nix value `v` to a GVariant `uchar` value (GVariant format string `y`).
+[[sec-option-types-gvariant-mkInt16]]`hm.gvariant.mkInt16 (v: int)`:::
+Takes a Nix value `v` to a GVariant `int16` value (GVariant format string `n`).
+[[sec-option-types-gvariant-mkUint16]]`hm.gvariant.mkUint16 (v: int)`:::
+Takes a Nix value `v` to a GVariant `uint16` value (GVariant format string `q`).
+[[sec-option-types-gvariant-mkInt32]]`hm.gvariant.mkInt32 (v: int)`:::
+Takes a Nix value `v` to a GVariant `int32` value (GVariant format string `i`). Note, Nix integers are automatically coerced using this function. That is,
 +
 [source,nix]
 ----
@@ -132,14 +132,14 @@ is equivalent to
 ----
 foo.bar = 7;
 ----
-`hm.gvariant.mkUint32 (v: int)`:::
-Takes a Nix value `v` to a GVariant `uint32` value.
-`hm.gvariant.mkInt64 (v: int)`:::
-Takes a Nix value `v` to a GVariant `int64` value.
-`hm.gvariant.mkUint64 (v: int)`:::
-Takes a Nix value `v` to a GVariant `uint64` value.
-`hm.gvariant.mkDouble (v: double)`:::
-Takes a Nix value `v` to a GVariant `double` value. Note, Nix floats are automatically coerced using this function. That is,
+[[sec-option-types-gvariant-mkUint32]]`hm.gvariant.mkUint32 (v: int)`:::
+Takes a Nix value `v` to a GVariant `uint32` value (GVariant format string `u`).
+[[sec-option-types-gvariant-mkInt64]]`hm.gvariant.mkInt64 (v: int)`:::
+Takes a Nix value `v` to a GVariant `int64` value (GVariant format string `x`).
+[[sec-option-types-gvariant-mkUint64]]`hm.gvariant.mkUint64 (v: int)`:::
+Takes a Nix value `v` to a GVariant `uint64` value (GVariant format string `t`).
+[[sec-option-types-gvariant-mkDouble]]`hm.gvariant.mkDouble (v: double)`:::
+Takes a Nix value `v` to a GVariant `double` value (GVariant format string `d`). Note, Nix floats are automatically coerced using this function. That is,
 +
 [source,nix]
 ----
@@ -153,43 +153,43 @@ is equivalent to
 foo.bar = 3.14;
 ----
 +
-`hm.gvariant.mkArray type elements`:::
-Builds a GVariant array containing the given list of elements, where each element is a GVariant value of the given type. The `type` value can be constructed using
+[[sec-option-types-gvariant-mkArray]]`hm.gvariant.mkArray type elements`:::
+Builds a GVariant array containing the given list of elements, where each element is a GVariant value of the given type (GVariant format string `a${type}`). The `type` value can be constructed using
 +
 --
-- `hm.gvariant.type.string`
-- `hm.gvariant.type.boolean`
-- `hm.gvariant.type.uchar`
-- `hm.gvariant.type.int16`
-- `hm.gvariant.type.uint16`
-- `hm.gvariant.type.int32`
-- `hm.gvariant.type.uint32`
-- `hm.gvariant.type.int64`
-- `hm.gvariant.type.uint64`
-- `hm.gvariant.type.double`
-- `hm.gvariant.type.variant`
-- `hm.gvariant.type.arrayOf type`
-- `hm.gvariant.type.maybeOf type`
-- `hm.gvariant.type.tupleOf types`
-- `hm.gvariant.type.dictionaryEntryOf types`
+- `hm.gvariant.type.string` (GVariant format string `s`)
+- `hm.gvariant.type.boolean` (GVariant format string `b`)
+- `hm.gvariant.type.uchar` (GVariant format string `y`)
+- `hm.gvariant.type.int16` (GVariant format string `n`)
+- `hm.gvariant.type.uint16` (GVariant format string `q`)
+- `hm.gvariant.type.int32` (GVariant format string `i`)
+- `hm.gvariant.type.uint32` (GVariant format string `u`)
+- `hm.gvariant.type.int64` (GVariant format string `x`)
+- `hm.gvariant.type.uint64` (GVariant format string `t`)
+- `hm.gvariant.type.double` (GVariant format string `d`)
+- `hm.gvariant.type.variant` (GVariant format string `v`)
+- `hm.gvariant.type.arrayOf type` (GVariant format string `a${type}`)
+- `hm.gvariant.type.maybeOf type` (GVariant format string `m${type}`)
+- `hm.gvariant.type.tupleOf types` (GVariant format string `(${lib.concatStrings types})`)
+- `hm.gvariant.type.dictionaryEntryOf [keyType valueType]` (GVariant format string `{${keyType}${valueType}}`)
 --
 +
 where `type` and `types` are themselves a type and list of types, respectively.
 +
-`hm.gvariant.mkEmptyArray type`:::
-An alias of `hm.gvariant.mkArray type []`.
+[[sec-option-types-gvariant-mkEmptyArray]]`hm.gvariant.mkEmptyArray type`:::
+An alias of <<sec-option-types-gvariant-mkArray,`hm.gvariant.mkArray type []`>>.
 +
-`hm.gvariant.mkNothing type`:::
-Builds a GVariant maybe value whose (non-existent) element is of the given type. The `type` value is constructed as described for the `mkArray` function above.
+[[sec-option-types-gvariant-mkNothing]]`hm.gvariant.mkNothing type`:::
+Builds a GVariant maybe value (GVariant format string `m${type}`) whose (non-existent) element is of the given type. The `type` value is constructed as described for the <<sec-option-types-gvariant-mkArray,`mkArray`>> function above.
 +
-`hm.gvariant.mkJust element`:::
-Builds a GVariant maybe value containing the given GVariant element.
+[[sec-option-types-gvariant-mkJust]]`hm.gvariant.mkJust element`:::
+Builds a GVariant maybe value (GVariant format string `m${element.type}`) containing the given GVariant element.
 +
-`hm.gvariant.mkTuple elements`:::
+[[sec-option-types-gvariant-mkTuple]]`hm.gvariant.mkTuple elements`:::
 Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value.
 +
-`hm.gvariant.mkVariant element`:::
-Builds a GVariant variant which contains the value of a GVariant element.
+[[sec-option-types-gvariant-mkVariant]]`hm.gvariant.mkVariant element`:::
+Builds a GVariant variant (GVariant format string `v`) which contains the value of a GVariant element.
 +
-`hm.gvariant.mkDictionaryEntry elements`:::
-Builds a GVariant dictionary entry containing the given list of elements, where each element is a GVariant value.
+[[sec-option-types-gvariant-mkDictionaryEntry]]`hm.gvariant.mkDictionaryEntry [key value]`:::
+Builds a GVariant dictionary entry containing the given list of elements (GVariant format string `{${key.type}${value.type}}`), where each element is a GVariant value.

modules/misc/dconf.nix

@@ -59,6 +59,17 @@ in {
         '';
         description = ''
           Settings to write to the dconf configuration system.
+          </para><para>
+          Note that the database is strongly-typed so you need to use the same types
+          as described in the GSettings schema. For example, if an option is of type
+          <literal>uint32</literal> (<literal>u</literal>), you need to wrap the number
+          using the <literal>lib.hm.gvariant.mkUint32</literal> constructor.
+          Otherwise, since Nix integers are implicitly coerced to <literal>int32</literal>
+          (<literal>i</literal>), it would get stored in the database as such, and GSettings
+          might be confused when loading the setting.
+          </para><para>
+          You might want to use <link xlink:href="https://github.com/gvolpe/dconf2nix">dconf2nix</link>
+          to convert dconf database dumps into compatible Nix expression.
         '';
       };
     };