Add some internal documentation for flake support objects.

3 files changed, 56 insertions, 4 deletions

diff --git a/src/libexpr/flake/flake.hh b/src/libexpr/flake/flake.hh
index 69c779af8..40476a137 100644
--- a/src/libexpr/flake/flake.hh
+++ b/src/libexpr/flake/flake.hh
@@ -17,20 +17,41 @@ struct FlakeInput;
 
 typedef std::map<FlakeId, FlakeInput> FlakeInputs;
 
+// FlakeInput is the flake-level parsed form of the "input" entries in
+// the flake file.
+//
+// A FlakeInput is normally constructed by initially
+// first constructing a FlakeRef (a fetcher, the fetcher-specific
+// representation of the input specification, and the fetched local
+// store path result) and then creating this FlakeInput to hold that
+// FlakeRef, along with anything that might override that FlakeRef
+// (like command-line overrides or "follows" specifications).
+//
+// A FlakeInput is also sometimes constructed directly from a FlakeRef
+// instead of starting at the flake-file input specification
+// (e.g. overrides, follows, and implicit inputs).
+//
+// A FlakeInput will usually have one of either "ref" or "follows"
+// set.  If not otherwise specified, a "ref" will be generated to a
+// 'type="indirect"' flake, which is treated as simply the name of a
+// flake to be resolved in the registry.
+
 struct FlakeInput
 {
     std::optional<FlakeRef> ref;
-    bool isFlake = true;
+    bool isFlake = true;  // true = process flake to get outputs, false = (fetched) static source path
     std::optional<InputPath> follows;
     bool absolute = false; // whether 'follows' is relative to the flake root
     FlakeInputs overrides;
 };
 
+// The Flake structure is the main internal representation of a flake.nix file.
+
 struct Flake
 {
-    FlakeRef originalRef;
-    FlakeRef resolvedRef;
-    FlakeRef lockedRef;
+    FlakeRef originalRef;   // the original flake specification (by the user)
+    FlakeRef resolvedRef;   // registry references and caching resolved to the specific underlying flake
+    FlakeRef lockedRef;     // the specific local store result of invoking the fetcher
     std::optional<std::string> description;
     std::shared_ptr<const fetchers::Tree> sourceInfo;
     FlakeInputs inputs;
diff --git a/src/libexpr/flake/flakeref.hh b/src/libexpr/flake/flakeref.hh
index f4eb825a6..ac68cde0e 100644
--- a/src/libexpr/flake/flakeref.hh
+++ b/src/libexpr/flake/flakeref.hh
@@ -12,10 +12,25 @@ class Store;
 
 typedef std::string FlakeId;
 
+// The FlakeRef represents a local nix store reference to a flake
+// input for a Flake (it may be helpful to think of this object by the
+// alternate name of "InputRefForFlake").  It is constructed by
+// starting with an input description (usually the attrs or a url from
+// the flake file), locating a fetcher for that input, and then
+// capturing the Input object that fetcher generates (usually via
+// FlakeRef::fromAttrs(attrs) or parseFlakeRef(url) calls).
+//
+// The actual fetch not have been performed yet (i.e. a FlakeRef may
+// be lazy), but the fetcher can be invoked at any time via the
+// FlakeRef to ensure the store is populated with this input.
+
 struct FlakeRef
 {
+    // fetcher-specific representation of the input, sufficient to
+    // perform the fetch operation.
     fetchers::Input input;
 
+    // sub-path within the fetched input that represents this input
     Path subdir;
 
     bool operator==(const FlakeRef & other) const;
diff --git a/src/libfetchers/fetchers.hh b/src/libfetchers/fetchers.hh
index 89b1e6e7d..f361edf17 100644
--- a/src/libfetchers/fetchers.hh
+++ b/src/libfetchers/fetchers.hh
@@ -21,6 +21,13 @@ struct Tree
 
 struct InputScheme;
 
+// The Input object is generated by a specific fetcher, based on the
+// user-supplied input attribute in the flake.nix file, and contians
+// the information that the specific fetcher needs to perform the
+// actual fetch.  The Input object is most commonly created via the
+// "fromURL()" or "fromAttrs()" static functions which are provided the
+// url or attrset specified in the flake file.
+
 struct Input
 {
     friend struct InputScheme;
@@ -82,6 +89,15 @@ public:
     std::optional<time_t> getLastModified() const;
 };
 
+
+// The InputScheme represents a type of fetcher.  Each fetcher
+// registers with nix at startup time.  When processing an input for a
+// flake, each scheme is given an opportunity to "recognize" that
+// input from the url or attributes in the flake file's specification
+// and return an Input object to represent the input if it is
+// recognized.  The Input object contains the information the fetcher
+// needs to actually perform the "fetch()" when called.
+
 struct InputScheme
 {
     virtual std::optional<Input> inputFromURL(const ParsedURL & url) = 0;