1 files changed, 15 insertions, 0 deletions
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;