[gnunet-scheme] branch master updated: doc: Extract server object documentation into a common location.

[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.

The following commit(s) were added to refs/heads/master by this push:
     new a00195d  doc: Extract server object documentation into a common 
location.
a00195d is described below

commit a00195d34848e58747d4fa2050c6ae99f04e4d0b
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Thu Sep 1 16:43:10 2022 +0200

    doc: Extract server object documentation into a common location.
    
    It's the same between services, let's avoid duplicating it for each
    service.
    
    * doc/typeclasses.tm: New chapter.
    * doc/distributed-hash-table.scm: Use new chapter.
    * doc/cadet.tm: Likewise.
    * doc/network-size-estimation.tm: Likewise.
    * doc/scheme-gnunet.tm: Insert new chapter.
---
 doc/cadet.tm                   |  9 +++++++-
 doc/distributed-hash-table.tm  | 33 +++++++---------------------
 doc/network-size-estimation.tm | 37 +++++++++++++------------------
 doc/scheme-gnunet.tm           |  4 ++++
 doc/typeclasses.tm             | 49 ++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 84 insertions(+), 48 deletions(-)

diff --git a/doc/cadet.tm b/doc/cadet.tm
index d7b93e4..6d7eaa3 100644
--- a/doc/cadet.tm
+++ b/doc/cadet.tm
@@ -10,7 +10,14 @@
     With some restrictions: there must be a path between the nodes, in a
     lossy and malicious network with few connections the connection will be
     lossy, etc.
-  </footnote>. Before describing the API the software can use, some
+  </footnote>. The client code is available from the <scm|(gnu gnunet cadet
+  client)><index|(gnu gnunet cadet client)> module, which implements the
+  <reference|server object> pattern \U <scm|connect><subindex|connect|CADET>
+  connects to the service and returns a <dfn|CADET server
+  object><subindex|server object|CADET> and
+  <scm|disconnect!><subindex|disconnect!|CADET> breaks the connection.
+
+  Before describing in more detail the API the software can use, some
   background on CADET's capabilities is given.
 
   <\warning>
diff --git a/doc/distributed-hash-table.tm b/doc/distributed-hash-table.tm
index 16f8656..8107321 100644
--- a/doc/distributed-hash-table.tm
+++ b/doc/distributed-hash-table.tm
@@ -8,31 +8,14 @@
   GNUnet has a service that maintains a <em|distributed hash
   table><index|distributed hash table><index|DHT><index|R5N>, mapping keys to
   values. The module <scm|(gnu gnunet dht client)><index|(gnu gnunet dht
-  client)> can be used to interact with the service. The connection can be
-  made with the procedure <scm|connect>. It returns a <em|DHT server
-  object><index|DHT server object><subindex|server object|DHT>.
-
-  <\explain>
-    <scm|(connect <var|config> <var|#:connected> <var|#:disconnected>
-    <var|#:spawn>)><subindex|connect|DHT><label|dht:connect>
-  <|explain>
-    Connect to the DHT service, using the configuration <var|config>. The
-    connection is made asynchronuously; the optional thunk <var|connected> is
-    called when the connection has been made. The connection can break; the
-    optional thunk <var|disconnected> is called when it does. If the
-    connection breaks, the client code automatically tries to reconnect, so
-    <var|connected> can be called after <var|disconnected>.
-  </explain>
-
-  <\explain>
-    <scm|(disconnect! <var|server>)><subindex|disconnect!|DHT>
-  <|explain>
-    Asynchronuously disconnect from the DHT service and stop reconnecting,
-    even if not connected. This is an idempotent operation.
-  </explain>
-
-  Some time after the returned server object becomes unreachable, it will
-  automatically be disconnected. Active lingering operations and reachable
+  client)> can be used to interact with the service. This module implements
+  the <reference|server object> pattern, including
+  <scm|connect><subindex|connect|DHT><label|dht:connect> and
+  <scm|disconnect!><subindex|disconnect!|DHT>, which act on <dfn|DHT server
+  objects><index|DHT server object><subindex|server object|DHT>. Keep in mind
+  that, according to the server object pattern, after the server object
+  becomes unreachable, it will automatically be disconnected, even if there
+  are active operations! However, active lingering operations and reachable
   operations keeps the server object reachable. <todo|test this!>
 
   <section|Data in the DHT>
diff --git a/doc/network-size-estimation.tm b/doc/network-size-estimation.tm
index 9167a27..1e23602 100644
--- a/doc/network-size-estimation.tm
+++ b/doc/network-size-estimation.tm
@@ -6,33 +6,26 @@
 
 <\body>
   <index|network size estimation><index|NSE>GNUnet has a service that roughly
-  estimates the size of the network \U i.e., the number of
-  peers.<space|1em>The module <scm|(gnu gnunet nse client)><index|(gnu gnunet
-  nse client)> can be used to interact with this service.<space|1em>The
-  connection is made with the procedure 
<scm|connect><subindex|connect|NSE><label|nse:connect>,
-  which is accepts a <em|<reference|configuration>> and some optional keyword
-  arguments.<space|1em>This procedure can be called as <scm|(connect config
-  #:updated updated #:connected connected #:disconnected
-  disconnected)>.<space|1em>It returns a <with|font-shape|italic|NSE server
-  object><index|NSE server object><subindex|server object|NSE>.
+  estimates the size of the network \U i.e., the number of peers. The module
+  <scm|(gnu gnunet nse client)><index|(gnu gnunet nse client)> can be used to
+  interact with this service, this module implements the
+  <em|<reference|server object>> pattern. The procedure
+  <scm|connect><subindex|connect|NSE><label|nse:connect> accepts one
+  additional optional keyword argument: <scm|#:updated <var|updated>>. As
+  usual, it returns a <dfn|NSE server object><index|NSE server
+  object><subindex|server object|NSE>. As usual,
+  <scm|disconnect!><subindex|disconnect!|NSE> can be called on the server
+  object to disconnect.
 
-  The connection is made asynchronuously; the thunk <var|connected> will be
-  called when the connection has actually been made.<space|1em>Whenever a new
-  estimate becomes available, the (optional) procedure
+  Whenever a new estimate becomes available, the (optional) procedure
   <var|updated><index|update procedure> is called with the new
   <with|font-shape|italic|estimate><index|estimate
   object>.<space|1em>Alternatively, the procedure
   <scm|estimate><index|estimate> can be called on the server object to return
-  the latest available estimate.<space|1em>If the
-  <with|font-shape|italic|server object> doesn't have an estimate yet, that
-  procedure will return <scm|#false> instead of an estimate.
-
-  When the connection is lost, the (optional) thunk <var|disconnected> is
-  called and <scm|(gnu gnunet nse client)> will retry
-  connecting.<space|1em>To close the current connection, if any, and stop
-  reconnecting, the idempotent procedure 
<scm|disconnect!><subindex|disconnect!|NSE>
-  can be called on the server object.<space|1em>The server object will also
-  be disconnected after the server object becomes unreachable.
+  the latest available estimate.<space|1em>If the <em|NSE server object>
+  doesn't have an estimate yet, that procedure will return <scm|#false>
+  instead of an estimate. As usual, the idempotent procedure
+  <scm|disconnect!><subindex|disconnect!|NSE>
 
   <todo|input, validation, I/O errors?>
 
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 2359858..ad5b4a1 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -224,6 +224,10 @@
 
   <include|network-structures.tm>
 
+  <chapter|Typeclasses \U common patterns>
+
+  <include|typeclasses.tm>
+
   <chapter|Communication with services>
 
   <include|service-communication.tm>
diff --git a/doc/typeclasses.tm b/doc/typeclasses.tm
new file mode 100644
index 0000000..c8ae38d
--- /dev/null
+++ b/doc/typeclasses.tm
@@ -0,0 +1,49 @@
+<TeXmacs|2.1>
+
+<project|scheme-gnunet.tm>
+
+<style|tmmanual>
+
+<\body>
+  The client APIs for the various GNUnet services have similar APIs. To avoid
+  redundantly restating the API for each service type, the common patterns
+  are stated here once and are referenced by the service-specific
+  documentation.
+
+  <section|Server objects>
+
+  GNUnet has many <dfn|services><index|service>. The module responsible for
+  interacting with the service is conventionally named <scm|(gnu gnunet NAME
+  client)>, where <var|NAME> depends on the service. To use a service, it
+  needs to be <dfn|connected><index|connect> to, with a procedure named
+  <scm|connect> and some optional keyword arguments. This procedure can be
+  called as <scm|(connect <var|config> #:connected <var|connected>
+  #:disconnected <var|disconnected>)>. It returns a <dfn|server
+  object><index|server object><label|server object> \U for each service,
+  there is a different type of server object.
+
+  The connection is made asynchronuously; the thunk <var|connected> will be
+  called when the connection has actually been made.
+
+  When the connection is lost, the (optional) thunk <var|disconnected> is
+  called and the implementation will retry connecting. To close the current
+  connection, if any, and stop reconnecting, the idempotent procedure
+  <scm|disconnect!><index|disconnect!> can be called on the server object.
+  The server object will also be disconnected after the server object becomes
+  unreachable.
+
+  Service types can support or require additional arguments.
+
+  <section|Server-associated objects>
+
+  <\todo>
+    todo
+  </todo>
+</body>
+
+<\initial>
+  <\collection>
+    <associate|page-medium|paper>
+    <associate|save-aux|false>
+  </collection>
+</initial>
\ No newline at end of file

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