02/04: store: Clarify documentation of 'valid-path?'.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 06b76accebd5c98ae50dc7ec4c3f4dad764a637e
Author: Ludovic Courtès <address@hidden>
Date:   Thu Feb 25 12:12:50 2016 +0100

    store: Clarify documentation of 'valid-path?'.
    
    * guix/store.scm (valid-path?): Improve docstring.
    * doc/guix.texi (The Store): Update accordingly.
---
 doc/guix.texi  |    9 ++++++++-
 guix/store.scm |    7 ++++++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index b48f988..2bebeed 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2913,7 +2913,14 @@ Procedures that make RPCs all take a server object as 
their first
 argument.
 
 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
-Return @code{#t} when @var{path} is a valid store path.
address@hidden invalid store items
+Return @code{#t} when @var{path} designates a valid store item and
address@hidden otherwise (an invalid item may exist on disk but still be
+invalid, for instance because it is the result of an aborted or failed
+build.)
+
+A @code{&nix-protocol-error} condition is raised if @var{path} is not
+prefixed by the store directory (@file{/gnu/store}).
 @end deffn
 
 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} 
address@hidden
diff --git a/guix/store.scm b/guix/store.scm
index 8123407..3d6cff4 100644
--- a/guix/store.scm
+++ b/guix/store.scm
@@ -582,7 +582,12 @@ encoding conversion errors."
     (operation (name args ...) docstring return ...)))
 
 (define-operation (valid-path? (string path))
-  "Return #t when PATH is a valid store path."
+  "Return #t when PATH designates a valid store item and #f otherwise (an
+invalid item may exist on disk but still be invalid, for instance because it
+is the result of an aborted or failed build.)
+
+A '&nix-protocol-error' condition is raised if PATH is not prefixed by the
+store directory (/gnu/store)."
   boolean)
 
 (define-operation (query-path-hash (store-path path))