doc: clarify consequences of `lib.meta.setName`

And remove unnecessary mention of `nix-env`

1 files changed, 6 insertions, 2 deletions

diff --git a/lib/meta.nix b/lib/meta.nix
index 675e1912d4be9..9a97afb1aa9b0 100644
--- a/lib/meta.nix
+++ b/lib/meta.nix
@@ -26,8 +26,12 @@ rec {
   dontDistribute = drv: addMetaAttrs { hydraPlatforms = []; } drv;
 
 
-  /* Change the symbolic name of a package for presentation purposes
-     (i.e., so that nix-env users can tell them apart).
+  /*
+  Change the [symbolic name of a derivation](https://nixos.org/manual/nix/stable/language/derivations.html#attr-name).
+
+  :::{.warning}
+  Dependent derivations will be rebuilt when the symbolic name is changed.
+  :::
   */
   setName = name: drv: drv // {inherit name;};