[gnunet-scheme] 01/05: cadet: Document open-channel!.

[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 f7d24674a520ef2ed358038523ed446efb3fe533
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Mon Aug 22 19:59:48 2022 +0200

    cadet: Document open-channel!.
    
    * gnu/gnunet/cadet/client.scm (open-channel!): Add docstring.
    * doc/cadet.tm (Connecting to an address): Document 'open-channel!'.
---
 doc/cadet.tm                | 24 ++++++++++++++++++++++++
 gnu/gnunet/cadet/client.scm |  3 +++
 2 files changed, 27 insertions(+)

diff --git a/doc/cadet.tm b/doc/cadet.tm
index 52bbad8..52e41fe 100644
--- a/doc/cadet.tm
+++ b/doc/cadet.tm
@@ -83,6 +83,30 @@
 
   <section|Connecting to an address>
 
+  <index|open-channel!>To connect to a CADET address, the <scm|open-channel!>
+  procedure is used:
+
+  <\explain>
+    <scm|(open-channel! <var|server> <var|address> <var|handlers>)>
+  <|explain>
+    Asynchronuously connect to the CADET address <var|address> via the CADET
+    server object <var|server>, returning a CADET channel object. When a
+    message is received, it is passed to the appropriate handler.
+
+    <todo|re-entrancy \U running open-channel! inside a #:connected
+    fallback?>
+
+    <todo|errors>
+
+    <todo|behaviour in case of blocking>
+  </explain>
+
+  To actually send and receive messages, the
+  <scm|channel-message-queue><index|channel-message-queue> can be used to
+  retrieve the <em|message queue> (see: <reference|message queue>) of the
+  channel and the procedure <scm|send-message!> can be used to send the
+  message to the message queue (see: <reference|send-message!>).
+
   <section|Performing I/O \U GNUnet style>
 
   <section|Performing I/O \U BSD style>
diff --git a/gnu/gnunet/cadet/client.scm b/gnu/gnunet/cadet/client.scm
index 868b461..1718a77 100644
--- a/gnu/gnunet/cadet/client.scm
+++ b/gnu/gnunet/cadet/client.scm
@@ -456,6 +456,9 @@ message @var{message}."
 
     ;; TODO: callbacks, message queue, actually test it
     (define* (open-channel! server address handlers)
+      "Asynchronuously connect to the cadet address @var{address} via the 
CADET server
+object @var{server}, returning a CADET channel object.  When a message is
+received, it is passed to the appropriate handler."
       (assert (and (server:cadet? server) (cadet-address? address)))
       (define error-handler stub)
       (define sender (make-channel-sender (delay channel)))

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