PSYC: message types, documentation

3 files changed, 43 insertions, 17 deletions

diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h
index aa5597fd3..50dcf7aef 100644
--- a/src/include/gnunet_multicast_service.h
+++ b/src/include/gnunet_multicast_service.h
@@ -189,7 +189,8 @@ struct GNUNET_MULTICAST_RequestHeader
   struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
 
   /**
-   * Number of the request fragment, monotonically increasing.
+   * Number of the request fragment.
+   * Monotonically increasing from 1.
    */
   uint64_t fragment_id GNUNET_PACKED;
 
diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h
index 88cf5a024..b67e3bdcb 100644
--- a/src/include/gnunet_protocols.h
+++ b/src/include/gnunet_protocols.h
@@ -2126,64 +2126,84 @@ extern "C"
  * PSYC message types
  ******************************************************************************/
 
-#define GNUNET_MESSAGE_TYPE_PSYC_RESULT_CODE 680
+/**
+ * C: client
+ * S: service
+ * M: muticast
+ */
 
+/** S->C: result of an operation */
+#define GNUNET_MESSAGE_TYPE_PSYC_RESULT_CODE 680
 
+/** C->S: request to start a master */
 #define GNUNET_MESSAGE_TYPE_PSYC_MASTER_START 681
 
+/** S->C: master start acknowledgement */
 #define GNUNET_MESSAGE_TYPE_PSYC_MASTER_START_ACK 682
 
-#define GNUNET_MESSAGE_TYPE_PSYC_MASTER_STOP 683
-
+/** C->S: request to start a master */
+#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN 683
 
-#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN 684
-
-#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN_ACK 685
-
-#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_PART 686
+/** S->C: slave join acknowledgement */
+#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN_ACK 684
 
+/* 685-686 */
 
+/** M->S->C: incoming join request from multicast */
 #define GNUNET_MESSAGE_TYPE_PSYC_JOIN_REQUEST 687
 
+/** C->S->M: decision about a join request */
 #define GNUNET_MESSAGE_TYPE_PSYC_JOIN_DECISION 688
 
 
+/** C->S: request to remove channel slave from the membership database. */
 #define GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_SLAVE_ADD 689
 
+/** C->S: request to add channel slave to the membership database */
 #define GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_SLAVE_RM 690
 
 
+/** M<->S<->C: PSYC message which contains one or more message parts. */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE 691
 
+/** Message part: method */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_METHOD 692
 
+/** Message part: modifier */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER 693
 
+/** Message part: modifier continuation */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MOD_CONT 694
 
+/** Message part: data */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_DATA 695
 
+/** Message part: end of message */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_END 696
 
+/** Message part: message cancelled */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_CANCEL 697
 
+/** S->C: message acknowledgment */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_ACK 698
 
+/* 699-700 */
 
+/** C->S: client requests channel history from PSYCstore. */
 #define GNUNET_MESSAGE_TYPE_PSYC_STORY_REQUEST 701
 
-#define GNUNET_MESSAGE_TYPE_PSYC_STORY_RESPONSE 702
+/** S->C: result for a channel history request */
+#define GNUNET_MESSAGE_TYPE_PSYC_STORY_RESULT 702
 
 
+/** C->S: request best matching state variable from PSYCstore. */
 #define GNUNET_MESSAGE_TYPE_PSYC_STATE_GET 703
 
+/** C->S: request state variables with a given prefix from PSYCstore. */
 #define GNUNET_MESSAGE_TYPE_PSYC_STATE_GET_PREFIX 704
 
-#define GNUNET_MESSAGE_TYPE_PSYC_STATE_RESPONSE 705
-
-#define GNUNET_MESSAGE_TYPE_PSYC_STATE_MODIFIER 706
-
-#define GNUNET_MESSAGE_TYPE_PSYC_STATE_MOD_CONT 707
+/** S->C: result for a state request. */
+#define GNUNET_MESSAGE_TYPE_PSYC_STATE_RESULT 705
 
 
 /*******************************************************************************
@@ -2196,7 +2216,7 @@ extern "C"
 #define GNUNET_MESSAGE_TYPE_CONVERSATION_AUDIO 730
 
 /**
- * Client -> Server message register a phone.
+ * Client -> Server message to register a phone.
  */
 #define GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_REGISTER 731
 
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h
index 3a0c713d5..018f012f4 100644
--- a/src/include/gnunet_psyc_service.h
+++ b/src/include/gnunet_psyc_service.h
@@ -113,6 +113,7 @@ enum GNUNET_PSYC_ChannelFlags
   GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY = 1 << 1
 };
 
+
 /**
  * PSYC channel policies.
  */
@@ -169,6 +170,7 @@ enum GNUNET_PSYC_MessageFlags
   GNUNET_PSYC_MESSAGE_REQUEST = 1 << 1
 };
 
+
 GNUNET_NETWORK_STRUCT_BEGIN
 
 /**
@@ -190,6 +192,7 @@ struct GNUNET_PSYC_MessageHeader
 
   /**
    * Number of the message this message part belongs to.
+   * Monotonically increasing from 1.
    */
   uint64_t message_id GNUNET_PACKED;
 
@@ -254,6 +257,7 @@ struct GNUNET_PSYC_MessageModifier
 
 GNUNET_NETWORK_STRUCT_END
 
+
 #define GNUNET_PSYC_MODIFIER_MAX_PAYLOAD        \
   GNUNET_MULTICAST_FRAGMENT_MAX_PAYLOAD         \
   - sizeof (struct GNUNET_PSYC_MessageModifier)
@@ -266,6 +270,7 @@ GNUNET_NETWORK_STRUCT_END
   GNUNET_MULTICAST_FRAGMENT_MAX_PAYLOAD         \
   - sizeof (struct GNUNET_MessageHeader)
 
+
 /**
  * Handle that identifies a join request.
  *
@@ -362,7 +367,7 @@ struct GNUNET_PSYC_Master;
  * Function called after the channel master started.
  *
  * @param cls Closure.
- * @param last_message_id Last message ID sent to the channel.
+ * @param max_message_id Last message ID sent to the channel.
  */
 typedef void
 (*GNUNET_PSYC_MasterStartCallback) (void *cls, uint64_t max_message_id);