[gnunet-scheme] 01/06: dht/client: Partially document get paths and put paths.

[gnunet]

This is an automated email from the git hooks/post-receive script.

maxime-devos pushed a commit to branch master
in repository gnunet-scheme.

commit 835ebdaf659833ce8749f9a71085158d999ddfa2
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Wed Jan 26 09:01:36 2022 +0000

    dht/client: Partially document get paths and put paths.
    
    * doc/scheme-gnunet.tm (Data in the DHT)[datum->search-result]: Add
      text about get-path and put-path.
    * gnu/gnunet/dht/client.scm (datum->search-result): Likewise.
---
 doc/scheme-gnunet.tm      | 25 ++++++++++++++++++++-----
 gnu/gnunet/dht/client.scm | 16 ++++++++++++++--
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index f242adf..37ec484 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -1121,11 +1121,26 @@
 
   <\explain>
     <scm|(datum-\<gtr\>search-result <var|datum> #:get-path #:put-path)>
-  </explain|Make a search result object for the datum <var|datum>. The datum
-  can be recovered with the accessor <scm|search-result-\<gtr\>datum>. It can
-  be tested if an object is a search result with the predicate
-  <scm|search-result?>. The optional keyword arguments <scm|get-path> and
-  <scm|put-path> are currently undocumented and untested.>
+  <|explain>
+    Make a search result object for the datum <var|datum>. The datum can be
+    recovered with the accessor <scm|search-result-\<gtr\>datum>. It can be
+    tested if an object is a search result with the predicate
+    <scm|search-result?>. The optional arguments <var|get-path> and
+    <var|put-path>, when not false, are bytevector slices consisting of a
+    list of <scm|/dht:path-element>.
+
+    The <var|get-path> , if any, is the path from the storage location to the
+    current peer. Conversely, the <var|put-path>, if any, is a path from the
+    peer that inserted the datum into the DHT to the storage location. The
+    <var|get-path> and <var|put-path> can be accessed with
+    <scm|search-result-get-path> and <scm|search-result-put-path>
+    respectively.
+
+    When the datum, get path and put path together are too large, a
+    <scm|&overly-large-paths> condition is raised. When the bytevector slice
+    length of <var|get-path> or <var|put-path> is not a multiple of the size
+    of a path element, then a <scm|&malformed-path> condition is raised.
+  </explain>
 
   <subsection|Accessing data in the DHT>
 
diff --git a/gnu/gnunet/dht/client.scm b/gnu/gnunet/dht/client.scm
index 1f922b2..928029f 100644
--- a/gnu/gnunet/dht/client.scm
+++ b/gnu/gnunet/dht/client.scm
@@ -288,8 +288,20 @@ query object with the predicate @code{query?}."
           "Make a search result object for the datum @var{datum}. The datum can
 be recovered with the accessor @code{search-result->datum}. It can be tested if
 an object is a search result with the predicate @code{search-result?}. The
-optional keyword arguments @code{get-path} and @code{put-path} are currently
-undocumented and untested."
+optional arguments @var{get-path} and @var{put-path}, when not false, are 
bytevector
+slices consisting of a list of @code{/dht:path-element}.
+
+The @var{get-path} , if any, is the path from the storage location to the
+current peer. Conversely, the @var{put-path}, if any, is a path from the
+peer that inserted the datum into the DHT to the storage location. The
+@var{get-path}} and @var{put-path} can be accessed with
+@code{search-result-get-path} and @code{search-result-put-path} respectively.
+
+When the datum, get path and put path together are too large, a
+@code{&overly-large-paths} condition is raised. When the
+bytevector slice length of @var{get-path} or @var{put-path} is not a
+multiple of the size of a path element, then a @code{&malformed-path}
+condition is raised."
           ;; TODO: can a get-path exist without a put-path?
           (let^ ((! (make-who)
                     (make-who-condition 'datum->search-result))

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.