From e531ac2ad9b9933711523cd2c76c1b9ad90d7041 Mon Sep 17 00:00:00 2001
From: Ludovic Courtès <ludo@gnu.org>
Date: Tue, 15 Jan 2013 23:32:13 +0100
Subject: doc: Start documenting (guix store).

* doc/guix.texi (The Store): Populate.
  (Introduction): Add cross-reference.  Change "package store" to "the
  store".
---
 doc/guix.texi  | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 guix/store.scm |  8 +++++++-
 2 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 7de7f4f0c2..1252caaf08 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -116,10 +116,10 @@ of its build and installation directories.  This is achieved by running
 build processes in dedicated ``chroots'', where only their explicit
 inputs are visible.
 
-@cindex package store
+@cindex store
 The result of package build functions is @dfn{cached} in the file
-system, in a special directory called the @dfn{package store}.  In
-practice, each package is installed in a directory of its own, in the
+system, in a special directory called @dfn{the store} (@pxref{The
+Store}).  Each package is installed in a directory of its own, in the
 store---by default under @file{/nix/store}.  The directory name contains
 a hash of all the inputs used to build that package; thus, changing an
 input yields a different directory name.
@@ -750,7 +750,58 @@ must be a connection to the daemon, which operates on the store
 @node The Store
 @section The Store
 
-@code{(guix store)}
+@cindex store
+@cindex store paths
+
+Conceptually, the @dfn{store} is where derivations that have been
+successfully built are stored---by default, under @file{/nix/store}.
+Sub-directories in the store are referred to as @dfn{store paths}.  The
+store has an associated database that contains information such has the
+store paths referred to by each store path, and the list of @emph{valid}
+store paths---paths that result from a successful build.
+
+The store is always accessed by the daemon on behalf of its clients
+(@pxref{Invoking guix-daemon}).  To manipulate the store, clients
+connect to the daemon over a Unix-domain socket, send it requests, and
+read the result---these are remote procedure calls, or RPCs.
+
+The @code{(guix store)} module provides procedures to connect to the
+daemon, and to perform RPCs.  These are described below.
+
+@deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
+Connect to the daemon over the Unix-domain socket at @var{file}.  When
+@var{reserve-space?} is true, instruct it to reserve a little bit of
+extra space on the file system so that the garbage collector can still
+operate, should the disk become full.  Return a server object.
+
+@var{file} defaults to @var{%default-socket-path}, which is the normal
+location given the options that were passed to @command{configure}.
+@end deffn
+
+@deffn {Scheme Procedure} close-connection @var{server}
+Close the connection to @var{server}.
+@end deffn
+
+@defvr {Scheme Variable} current-build-output-port
+This variable is bound to a SRFI-39 parameter, which refers to the port
+where build and error logs sent by the daemon should be written.
+@end defvr
+
+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.
+@end deffn
+
+@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references}
+Add @var{text} under file @var{name} in the store, and return its store
+path.  @var{references} is the list of store paths referred to by the
+resulting store path.
+@end deffn
+
+@c FIXME
+@i{This section is currently incomplete.}
 
 @node Derivations
 @section Derivations
diff --git a/guix/store.scm b/guix/store.scm
index 5111d8f50a..c7eb9a7605 100644
--- a/guix/store.scm
+++ b/guix/store.scm
@@ -308,6 +308,10 @@
 
 (define* (open-connection #:optional (file %default-socket-path)
                           #:key (reserve-space? #t))
+  "Connect to the daemon over the Unix-domain socket at FILE.  When
+RESERVE-SPACE? is true, instruct it to reserve a little bit of extra
+space on the file system so that the garbage collector can still
+operate, should the disk become full.  Return a server object."
   (let ((s (with-fluids ((%default-port-encoding #f))
              ;; This trick allows use of the `scm_c_read' optimization.
              (socket PF_UNIX SOCK_STREAM 0)))
@@ -446,7 +450,9 @@ again until #t is returned or an error is raised."
 
 (define-operation (add-text-to-store (string name) (string text)
                                      (string-list references))
-  "Add TEXT under file NAME in the store."
+  "Add TEXT under file NAME in the store, and return its store path.
+REFERENCES is the list of store paths referred to by the resulting store
+path."
   store-path)
 
 (define-operation (add-to-store (string basename)
-- 
cgit v1.2.3