packages: Recommend against the use of 'package-file'.

* guix/packages.scm (package-file): Recommend against its use in the
docstring.
* doc/guix.texi (The Store Monad): Likewise.

1 files changed, 4 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index d2cd11576f..a79bbfc4f7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7483,6 +7483,10 @@ value in the absolute file name of @var{file} within the @var{output}
 directory of @var{package}.  When @var{file} is omitted, return the name
 of the @var{output} directory of @var{package}.  When @var{target} is
 true, use it as a cross-compilation target triplet.
+
+Note that this procedure does @emph{not} build @var{package}.  Thus, the
+result might or might not designate an existing file.  We recommend not
+using this procedure unless you know what you are doing.
 @end deffn
 
 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]