diff --git a/src/libfetchers/fetchers.hh b/src/libfetchers/fetchers.hh
index 430d6e943..1ea75ba84 100644
--- a/src/libfetchers/fetchers.hh
+++ b/src/libfetchers/fetchers.hh
@@ -92,10 +92,9 @@ public:
 
     /**
      * Return whether this is a "final" input, meaning that fetching
-     * it will not add, remove or change any attributes. For instance,
-     * a Git input with a `rev` attribute but without a `lastModified`
-     * attribute is considered locked but not final. Only "final"
-     * inputs can be substituted from a binary cache.
+     * it will not add, remove or change any attributes. (See
+     * `checkLocks()` for the semantics.) Only "final" inputs can be
+     * substituted from a binary cache.
      *
      * The "final" state is denoted by the presence of an attribute
      * `__final = true`. This attribute is currently undocumented and
diff --git a/src/nix/flake.md b/src/nix/flake.md
index b3321441c..e35b936be 100644
--- a/src/nix/flake.md
+++ b/src/nix/flake.md
@@ -148,7 +148,7 @@ reference types:
 
 * `ref`: A Git or Mercurial branch or tag name.
 
-Finally, some attribute are typically not specified by the user, but
+Finally, some attributes are typically not specified by the user, but
 can occur in *locked* flake references and are available to Nix code:
 
 * `revCount`: The number of ancestors of the commit `rev`.
@@ -159,6 +159,8 @@ can occur in *locked* flake references and are available to Nix code:
   for tarball flakes, it's the most recent timestamp of any file
   inside the tarball.
 
+Attributes that start with `__` are internal or experimental and may be removed in future versions.
+
 ## Types
 
 Currently the `type` attribute can be one of the following: