lib/generators: improve documentation a bit

1 files changed, 11 insertions, 0 deletions

diff --git a/lib/generators.nix b/lib/generators.nix
index 64399ddd50a..6adf0c2afbc 100644
--- a/lib/generators.nix
+++ b/lib/generators.nix
@@ -4,6 +4,12 @@
  * They all follow a similar interface:
  * generator { config-attrs } data
  *
+ * `config-attrs` are “holes” in the generators
+ * with sensible default implementations that
+ * can be overwritten. The default implementations
+ * are mostly generators themselves, called with
+ * their respective default values; they can be reused.
+ *
  * Tests can be found in ./tests.nix
  * Documentation in the manual, #sec-generators
  */
@@ -20,6 +26,8 @@ in
 
 rec {
 
+  ## -- HELPER FUNCTIONS & DEFAULTS --
+
   /* Generate a line of key k and value v, separated by
    * character sep. If sep appears in k, it is escaped.
    * Helper for synaxes with different separators.
@@ -35,6 +43,9 @@ rec {
     "${libStr.escape [sep] k}${sep}${mkValueString v}";
 
 
+  ## -- FILE FORMAT GENERATORS --
+
+
   /* Generate a key-value-style config file from an attrset.
    *
    * mkKeyValue is the same as in toINI.