a bit of comments (#30)

Author: vic

nix/aspects.nix

@@ -1,18 +1,21 @@
+# Transpose aspects.<aspect>.<class> to modules.<class>.<aspect>
+# Resolves aspect dependencies and applies transformations during transposition
+
 lib: aspects:
 let
+  # Import transpose utility with custom emit function for aspect resolution
   transpose = import ./. { inherit lib emit; };
-  emit =
-    transposed:
-    let
-      aspect = aspects.${transposed.child};
-    in
-    [
-      {
-        inherit (transposed) parent child;
-        value = aspect.resolve { class = transposed.parent; };
-      }
-    ];
+
+  # Emit function: resolves each aspect for its target class
+  # Returns: [{ parent = class, child = aspect, value = resolved-module }]
+  emit = transposed: [
+    {
+      inherit (transposed) parent child;
+      value = aspects.${transposed.child}.resolve { class = transposed.parent; };
+    }
+  ];
 in
 {
+  # Exports: transposed.<class>.<aspect> = resolved-module
   transposed = transpose aspects;
 }

nix/default.nix

@@ -1,11 +1,21 @@
+# Generic 2-level attribute set transposition
+# Swaps parent/child levels: { a.b = 1; } → { b.a = 1; }
+# Parameterized via emit function for custom value handling
+
 {
   lib,
+  # emit: Customization function for each item during transpose
+  # Signature: { child, parent, value } → [{ parent, child, value }]
+  # Default: lib.singleton (identity transformation)
   emit ? lib.singleton,
 }:
 let
+  # Create transposition metadata by calling emit
   transposeItem =
     child: parent: value:
     emit { inherit child parent value; };
+
+  # Fold accumulator: rebuilds transposed structure
   accTransposed =
     acc: item:
     acc
@@ -14,9 +24,17 @@ let
         ${item.child} = item.value;
       };
     };
+
+  # Process all children of a parent
   transposeItems = parent: lib.mapAttrsToList (transposeItem parent);
+
+  # Flatten input into transposition items
   deconstruct = lib.mapAttrsToList transposeItems;
+
+  # Fold items back into swapped structure
   reconstruct = lib.foldl accTransposed { };
+
+  # Main transpose: deconstruct → flatten → reconstruct
   transpose =
     attrs:
     lib.pipe attrs [

nix/flakeModule.nix

@@ -1,9 +1,16 @@
+# Flake-parts integration for aspect-oriented configuration
+# Provides flake.aspects (input) and flake.modules (output)
+
 {
   lib,
   config,
   ...
 }:
+# Invoke new() factory to create flake.aspects and flake.modules
 import ./new.nix lib (option: transposed: {
+  # User-facing aspects input
   options.flake.aspects = option;
+
+  # Computed modules output organized by class
   config.flake.modules = transposed;
 }) config.flake.aspects

nix/lib.nix

@@ -1,13 +1,24 @@
+# Public API entry point for flake-aspects library
+# Exports: types, transpose, aspects, new, new-scope
 lib:
 let
+  # Type system: aspectsType, aspectSubmodule, providerType
   types = import ./types.nix lib;
+
+  # Generic transposition utility: parameterized by emit function
   transpose =
     {
       emit ? lib.singleton,
     }:
     import ./default.nix { inherit lib emit; };
+
+  # Aspect transposition with resolution
   aspects = import ./aspects.nix lib;
+
+  # Low-level scope factory: parameterized by callback
   new = import ./new.nix lib;
+
+  # High-level named scope factory
   new-scope = import ./new-scope.nix new;
 in
 {

nix/new-scope.nix

@@ -1,22 +1,14 @@
-# usage:
-#
-# { inputs, ... }: {
-#   imports = [ (new-scope "foo") ];
-#   foo.aspects.<aspect> = ...;
-#   # and use foo.modules.<class>.<aspect>
-# }
-#
-# returns a nix module that defines the ${name} option having:
-#
-#   options.${name}.aspects # for user
-#   options.${name}.modules # read-only resolved modules.
-#
-# for lower-level usage like using other option names, see new.nix.
+# Creates named aspect scopes: ${name}.aspects and ${name}.modules
+# Enables multiple independent aspect namespaces
 new: name:
 { config, lib, ... }:
+# Invoke new() to create ${name}.aspects and ${name}.modules
 new (option: transposed: {
   options.${name} = {
+    # User-facing aspects input
     aspects = option;
+
+    # Computed modules output (read-only)
     modules = lib.mkOption {
       readOnly = true;
       default = transposed;

nix/new.nix

@@ -1,17 +1,19 @@
-# creates a new aspects option.
-# See flakeModule for usage.
+# Low-level aspect scope factory
+# Creates aspect integration via callback pattern for maximum flexibility
 lib: cb: cfg:
 let
+  # Import aspects transposer: validates and transposes aspect config
   aspects = import ./aspects.nix lib cfg;
+
+  # Import type system for aspect validation
   types = import ./types.nix lib;
+
+  # Create aspects input option
   option = lib.mkOption {
     default = { };
-    description = ''
-      Attribute set of `<aspect>.<class>` modules.
-
-      Convenience transposition of `flake.modules.<class>.<aspect>`.
-    '';
+    description = "Aspect definitions organized as <aspect>.<class>";
     type = types.aspectsType;
   };
 in
+# Invoke callback with option and transposed results
 cb option aspects.transposed

nix/resolve.nix

@@ -1,13 +1,17 @@
+# Core aspect resolution algorithm
+# Resolves aspect definitions into nixpkgs modules with dependency resolution
+
 lib:
 let
-
+  # Process a single provider: invoke with context and resolve
   include =
     class: aspect-chain: provider:
     let
       provided = provider { inherit aspect-chain class; };
     in
     resolve class aspect-chain provided;
 
+  # Main resolution: extract class config and recursively resolve includes
   resolve = class: aspect-chain: provided: {
     imports = lib.flatten [
       (provided.${class} or { })