[gnunet-scheme] 01/02: doc: Set the ‘message-symbol’ property for DHT network structures.

[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 f55e0a7e525884b54a69dae1cb4776519079e27c
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Fri Feb 4 19:57:36 2022 +0000

    doc: Set the ‘message-symbol’ property for DHT network structures.
    
    * doc/scheme-gnunet.tm
      (Documentation): Document the 'message-symbol' property.
    * gnu/gnunet/dht/struct.scm: Set 'message-symbol' where appropriate.
---
 NEWS                      |  5 +++++
 doc/scheme-gnunet.tm      | 24 +++++++++++++++++++++++-
 gnu/gnunet/dht/struct.scm | 12 +++++++++++-
 3 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index fc71214..d3f71a1 100644
--- a/NEWS
+++ b/NEWS
@@ -6,6 +6,11 @@
 # without any warranty.
 
 -*- mode: org; coding: utf-8 -*-
+* Changes since 0.2
+** Documentation
+   - The ‘message-symbol’ network structure property is now defined for DHT
+     messages and documented in the manual.  The aim is to make the code
+     a little more self-documenting and understandable.
 * Changes since 0.1
 ** Features
    - A DHT client! (gnu gnunet dht client), documented in the manual
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index f14e836..fa06771 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -614,6 +614,27 @@
   with <scm|structure/packed> and individual fields and can be accessed with
   the procedures <scm|documentation>, <scm|synopsis> and <scm|properties>.
 
+  The following properties are defined in Scheme-GNUnet:
+
+  <\description>
+    <\item*>
+      <\code>
+        message-symbol
+      </code>
+    </item*>
+
+    <index|message-symbol>For <with|font-shape|italic|message structures>,
+    this is a list of the names of the <with|font-shape|italic|message types>
+    (see <reference|sec:message type> Message type database) this structure
+    can be used for \U most of the time, there's only a single such message
+    type, but sometimes a single structure can be used for multiple message
+    types.
+  </description>
+
+  <todo|TODO: it would be nice to use the properties and documentation to
+  automatically create a form of documentation, with some cross-references to
+  the C code>
+
   <section|Reading and writing>
 
   The procedures <scm|read%><index|read%>, <scm|set%!><index|set%!>,
@@ -838,7 +859,8 @@
 
   <todo|document the message type database, various procedures>
 
-  <section|Message type database><subindex|message type|database>
+  <section|Message type database><label|sec:message type><subindex|message
+  type|database>
 
   The module <scm|(gnu gnunet message protocols)><index|(gnu gnunet message
   protocols)> has a mapping of symbolic names of every message type known to
diff --git a/gnu/gnunet/dht/struct.scm b/gnu/gnunet/dht/struct.scm
index 644d4dd..5889278 100644
--- a/gnu/gnunet/dht/struct.scm
+++ b/gnu/gnunet/dht/struct.scm
@@ -30,7 +30,7 @@
          /:msg:dht:monitor:get
          /:msg:dht:monitor:get-response)
   (import (only (rnrs base)
-               define begin)
+               define begin quote)
          (only (gnu gnunet util struct)
                /:message-header /time-absolute)
          (only (gnu gnunet hashcode struct)
@@ -66,6 +66,7 @@ path element.")) ;; C GNUnet says somethin about a 
non-existent ‘succ’ field
       (structure/packed
        (synopsis "Message indicating the DHT should cancel outstanding requests
 and discard any state.")
+       (properties '((message-symbol msg:dht:client:get:stop)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:client:get:stop"))
        (field (reserved u32/big)
@@ -80,6 +81,7 @@ and discard any state.")
       (structure/packed
        (synopsis "DHT GET message sent from clients to service, indicating a 
GET
 request should be issued.")
+       (properties '((message-symbol msg:dht:client:get)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:client:get"))
        (field (options u32/big)
@@ -99,6 +101,7 @@ will not expect a response"))))
       (structure/packed
        (synopsis "Message sent from clients to service, indicating a GET 
request
 should exclude certain results which are already known.")
+       (properties '((message-symbol msg:dht:client:get-result-known)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:client:get-results-known"))
        (field (reserved u32/big)
@@ -113,6 +116,7 @@ corresponding GET inside the service)."))
     (define-type /:msg:dht:client:result
       (structure/packed
        (synopsis "Reply to a GET sent from the service to a client")
+       (properties '((message-symbol msg:dht:client:result)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:client:result"))
        (field (type u32/big)
@@ -135,6 +139,7 @@ location to this peer."))
       (structure/packed
        (synopsis "Message to insert data into the DHT, sent from clients to DHT
 service")
+       (properties '((message-symbol msg:dht:client:put)))
        (field (header /:message-header)
              (synopsis "Type msg:dht:client:put"))
        (field (type u32/big)
@@ -153,6 +158,7 @@ service")
       (structure/packed
        (synopsis "Message to monitor put requests going through peer
 (DHT service -> clients)")
+       (properties '((message-symbol msg:dht:monitor:put)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:monitor:put"))
        (field (options u32/big)
@@ -175,6 +181,8 @@ source to the target location of this message."))
       (structure/packed
        ;; TODO: also to stop monitoring messages?
        (synopsis "Message to request monitoring messages, client -> DHT 
service")
+       (properties '((message-symbol msg:dht:monitor:start
+                                    msg:dht:monitor:stop)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:monitor:start or msg:dht:monitor:stop"))
        (field (type u32/big)
@@ -200,6 +208,7 @@ source to the target location of this message."))
       (structure/packed
        (synopsis "Message to monitor get requests going through peer,
 DHT service -> clients.")
+       (properties '((message-symbol msg:dht:monitor:get)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:monitor:get"))
        (field (options u32/big)
@@ -221,6 +230,7 @@ source to the storage location of this message"))
       (structure/packed
        (synopsis "Message to monitor get requests going through peer,
 DHT service -> clients")
+       (properties '((message-symbol msg:dht:p2p:result)))
        (field (header /:message-header)
              ;; XXX correct?
              (synopsis "Type: msg:dht:p2p:result"))

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