Merge pull request #4080 from kquick/kwq/flake-int-doc

Add some internal documentation for flake support objects.

src/libexpr/flake/flake.hh

@@ -17,20 +17,43 @@ 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 the 'parseFlakeInput'
+ * function which parses the input specification in the '.flake' file
+ * to create a 'FlakeRef' (a fetcher, the fetcher-specific
+ * representation of the input specification, and possibly 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;

src/libexpr/flake/flakeref.hh

@@ -12,10 +12,33 @@ class Store;
 
 typedef std::string FlakeId;
 
+/* A flake reference specifies how to fetch a flake or raw source
+ * (e.g. from a Git repository).  It is created from a URL-like syntax
+ * (e.g. 'github:NixOS/patchelf'), an attrset representation (e.g. '{
+ * type="github"; owner = "NixOS"; repo = "patchelf"; }'), or a local
+ * path.
+ *
+ * Each flake will have a number of FlakeRef objects: one for each
+ * input to the flake.
+ *
+ * The normal method of constructing a FlakeRef is 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;

src/libfetchers/fetchers.hh

@@ -21,6 +21,14 @@ 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 contains
+ * 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;
@@ -84,6 +92,16 @@ 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 ~InputScheme()