lib, mkDerivation: Document overriding functions (#428563)

lib/customisation.nix

@@ -166,7 +166,16 @@ rec {
         overrideWith = newArgs: origArgs // (if isFunction newArgs then newArgs origArgs else newArgs);
 
         # Re-call the function but with different arguments
-        overrideArgs = mirrorArgs (newArgs: makeOverridable f (overrideWith newArgs));
+        overrideArgs = mirrorArgs (
+          /**
+            Change the arguments with which a certain function is called.
+
+            In some cases, you may find a list of possible attributes to pass in this function's `__functionArgs` attribute, but it will not be complete for an original function like `args@{foo, ...}: ...`, which accepts arbitrary attributes.
+
+            This function was provided by `lib.makeOverridable`.
+          */
+          newArgs: makeOverridable f (overrideWith newArgs)
+        );
         # Change the result of the function call by applying g to it
         overrideResult = g: makeOverridable (mirrorArgs (args: g (f args))) origArgs;
       in
@@ -176,6 +185,16 @@ rec {
           override = overrideArgs;
           overrideDerivation = fdrv: overrideResult (x: overrideDerivation x fdrv);
           ${if result ? overrideAttrs then "overrideAttrs" else null} =
+            /**
+              Override the attributes that were passed to `mkDerivation` in order to generate this derivation.
+
+              This function is provided by `lib.makeOverridable`, and indirectly by `callPackage` among others, in order to make the combination of `override` and `overrideAttrs` work.
+              Specifically, it re-adds the `override` attribute to the result of `overrideAttrs`.
+
+              The real implementation of `overrideAttrs` is provided by `stdenv.mkDerivation`.
+            */
+            # NOTE: part of the above documentation had to be duplicated in `mkDerivation`'s `overrideAttrs`.
+            #       design/tech debt issue: https://github.com/NixOS/nixpkgs/issues/273815
             fdrv: overrideResult (x: x.overrideAttrs fdrv);
         }
       else if isFunction result then

pkgs/stdenv/generic/make-derivation.nix

@@ -84,6 +84,10 @@ let
       args = rattrs (args // { inherit finalPackage overrideAttrs; });
       #              ^^^^
 
+      /**
+        Override the attributes that were passed to `mkDerivation` in order to generate this derivation.
+      */
+      # NOTE: the above documentation had to be duplicated in `lib/customisation.nix`: `makeOverridable`.
       overrideAttrs =
         f0:
         let