makeHardcodeGsettingsPatch: Improve docs

- Describe arguments and usage in more detail.
- Use finalAttrs in example.
- Use schema id, not path.
- Schema id is not what is replaced.

2 files changed, 40 insertions, 21 deletions

diff --git a/pkgs/build-support/make-hardcode-gsettings-patch/default.nix b/pkgs/build-support/make-hardcode-gsettings-patch/default.nix
index a1d2de21c4cb3..a4a2dc36df053 100644
--- a/pkgs/build-support/make-hardcode-gsettings-patch/default.nix
+++ b/pkgs/build-support/make-hardcode-gsettings-patch/default.nix
@@ -6,15 +6,35 @@
 }:
 
 /*
-  Can be used as part of an update script to automatically create a patch
-  hardcoding the path of all GSettings schemas in C code.
-  For example:
-  passthru = {
-    hardcodeGsettingsPatch = makeHardcodeGsettingsPatch {
-      inherit src;
-      schemaIdToVariableMapping = {
-         ...
-      };
+  Creates a patch that replaces every instantiation of GSettings in a C project
+  with a code that loads a GSettings schema from a hardcoded path.
+
+  This is useful so that libraries can find schemas even though Nix lacks
+  a standard location like /usr/share, where GSettings system could look for schemas.
+  The derivation is is somewhat dependency-heavy so it is best used as part of an update script.
+
+  For each schema id referenced in the source code (e.g. org.gnome.evolution),
+  a variable name such as `EVOLUTION` must be provided.
+  It will end up in the generated patch as `@EVOLUTION@` placeholder, which should be replaced at build time
+  with a path to the directory containing a `gschemas.compiled` file that includes the schema.
+
+
+  Arguments:
+  - `src`: source to generate the patch for.
+
+  - `schemaIdToVariableMapping`: attrset assigning schema ids to variable names.
+    All used schemas must be listed.
+
+    For example, `{ "org.gnome.evolution" = "EVOLUTION_SCHEMA_PATH"; }`
+    hardcodes looking for `org.gnome.evolution` into `@EVOLUTION_SCHEMA_PATH@`.
+
+  Example:
+    passthru = {
+      hardcodeGsettingsPatch = makeHardcodeGsettingsPatch {
+        inherit (finalAttrs) src;
+        schemaIdToVariableMapping = {
+           ...
+        };
     };
 
     updateScript =
@@ -26,12 +46,8 @@
         updateSource
         updatePatch
       ];
-    };
-  }
-  takes as input a mapping from schema path to variable name.
-  For example `{ "org.gnome.evolution" = "EVOLUTION_SCHEMA_PATH"; }`
-  hardcodes looking for `org.gnome.evolution` into `@EVOLUTION_SCHEMA_PATH@`.
-  All schemas must be listed.
+      };
+    }
 */
 {
   src,
diff --git a/pkgs/build-support/make-hardcode-gsettings-patch/hardcode-gsettings.cocci b/pkgs/build-support/make-hardcode-gsettings-patch/hardcode-gsettings.cocci
index a265f5fac384e..e916d74fd1f58 100644
--- a/pkgs/build-support/make-hardcode-gsettings-patch/hardcode-gsettings.cocci
+++ b/pkgs/build-support/make-hardcode-gsettings-patch/hardcode-gsettings.cocci
@@ -1,11 +1,14 @@
 /**
- * Since Nix does not have a standard location like /usr/share,
- * where GSettings system could look for schemas, we need to point the software to a correct location somehow.
+ * Since Nix does not have a standard location like /usr/share where GSettings system
+ * could look for schemas, we need to point the software to a correct location somehow.
  * For executables, we handle this using wrappers but this is not an option for libraries like e-d-s.
- * Instead, we hardcode the schema path when creating the settings.
- * A schema path (ie org.gnome.evolution) can be replaced by @EVOLUTION_SCHEMA_ID@
- * which is then replaced at build time by substituteAll.
- * The mapping is provided in a json file ./glib-schema-to-var.json
+ * Instead, we patch the source code to look for the schema in a schema source
+ * through a hardcoded path to the schema.
+ *
+ * For each schema id referenced in the source code (e.g. org.gnome.evolution),
+ * a variable name such as `EVOLUTION` must be provided in the ./glib-schema-to-var.json JSON file.
+ * It will end up in the resulting patch as `@EVOLUTION@` placeholder, which should be replaced at build time
+ * with a path to the directory containing a `gschemas.compiled` file that includes the schema.
  */
 
 @initialize:python@