diff --git a/src/libfetchers/attrs.hh b/src/libfetchers/attrs.hh
index 9f885a793..b9a2c824e 100644
--- a/src/libfetchers/attrs.hh
+++ b/src/libfetchers/attrs.hh
@@ -13,6 +13,12 @@
 namespace nix::fetchers {
 
 typedef std::variant<std::string, uint64_t, Explicit<bool>> Attr;
+
+/**
+ * An `Attrs` can be thought of a JSON object restricted or simplified
+ * to be "flat", not containing any subcontainers (arrays or objects)
+ * and also not containing any `null`s.
+ */
 typedef std::map<std::string, Attr> Attrs;
 
 Attrs jsonToAttrs(const nlohmann::json & json);
diff --git a/src/libfetchers/fetchers.cc b/src/libfetchers/fetchers.cc
index e683b9f80..7bffb04ff 100644
--- a/src/libfetchers/fetchers.cc
+++ b/src/libfetchers/fetchers.cc
@@ -254,7 +254,8 @@ std::optional<Hash> Input::getRev() const
         try {
             hash = Hash::parseAnyPrefixed(*s);
         } catch (BadHash &e) {
-            // Default to sha1 for backwards compatibility with existing flakes
+            // Default to sha1 for backwards compatibility with existing
+            // usages (e.g. `builtins.fetchTree` calls or flake inputs).
             hash = Hash::parseAny(*s, htSHA1);
         }
     }
diff --git a/src/libfetchers/fetchers.hh b/src/libfetchers/fetchers.hh
index 6e10e9513..b27ac4128 100644
--- a/src/libfetchers/fetchers.hh
+++ b/src/libfetchers/fetchers.hh
@@ -22,12 +22,11 @@ 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 `Input` object is generated by a specific fetcher, based on
+ * user-supplied information, 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.
+ * `fromURL()` or `fromAttrs()` static functions.
  */
 struct Input
 {
@@ -44,10 +43,20 @@ struct Input
     std::optional<Path> parent;
 
 public:
+    /**
+     * Create an `Input` from a URL.
+     *
+     * The URL indicate which sort of fetcher, and provides information to that fetcher.
+     */
     static Input fromURL(const std::string & url, bool requireTree = true);
 
     static Input fromURL(const ParsedURL & url, bool requireTree = true);
 
+    /**
+     * Create an `Input` from a an `Attrs`.
+     *
+     * The URL indicate which sort of fetcher, and provides information to that fetcher.
+     */
     static Input fromAttrs(Attrs && attrs);
 
     ParsedURL toURL() const;
@@ -116,13 +125,13 @@ public:
 
 
 /**
- * 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.
+ * The `InputScheme` represents a type of fetcher.  Each fetcher
+ * registers with nix at startup time.  When processing an `Input`,
+ * each scheme is given an opportunity to "recognize" that
+ * input from the user-provided url or attributes
+ * 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
 {