Write more comments

Some of these will become part of README.md later.

lib/flake-builders.nix

@@ -1,9 +1,8 @@
-# These functions take bi-level attrsets generated by rakeLeaves.
+# These functions take bi-level attrsets generated by `./rake.nix`.
 # Each leaf of the input attrset represents an unbuilt derivation,
 # its type being:
 # - for chart data, `{repo, chart, version, hash}`, or
-# - for release data:
-#     `module :: {lib} -> {builder, args, extraObjects}`.
+# - for release data: `{lib} -> {builder, args, extraObjects}`.
 # In other words, these builders transform these:
 # - repos.bjw-s.app-template = {repo, chart, version, hash}
 # - releaseData.svc.breezewiki = {lib}: {builder, args, extraObjects}
@@ -39,7 +38,7 @@ in {
           release.builder
           (release.args // {inherit name namespace;})
         # By injecting `name` and `namespace` here, I remove
-        # the need to specify it for every release in the flake;
+        # the need to specify it in every release in the flake;
         # the directory structure can speak for me instead.
       ))
       releases);
@@ -62,6 +61,9 @@ in {
       ))
       releases);
 
+  # Unlike the others, this builder's signature is:
+  # [attrset] -> <derivation>
+  # The output is a YAML stream of rendered namespaces.
   namespaces = objs:
     lib.builders.yamlStream {
       name = "namespaces";

lib/rake.nix

@@ -1,3 +1,8 @@
+# Data from `charts/` and `releases/` is gathered into
+# nested attrsets resembling the directory structure.
+# For example, `rake.leaves ./charts` produces:
+# {"bjw-s"={"app-template"={...}}; ...}; ...}
+# The data each leaf contains is explained in `./flake-builders.nix`.
 let
   ls = dir: with builtins; attrNames (readDir dir);