Doc fixes

docs/api/api-to-markdown.py

@@ -47,6 +47,7 @@
 #
 # "Inputs: none."
 # "Outputs: none."
+# "Member variable."
 # "Inputs:" followed by markdown (typically an unordered list) until the next match from this list.
 # "Outputs:" followed by markdown
 # "Example input:" followed by a code block (i.e. containing json)
@@ -91,6 +92,7 @@
 DEV_RPC_START = re.compile(r"^Dev-API:\s*([\w/:]+)(.*)$")
 IN_NONE = re.compile(r"^Inputs?: *[nN]one\.?$")
 IN_SOME = re.compile(r"^Inputs?:\s*$")
+MEMBER_VAR = re.compile(r"^Member +[vV]ar(?:iable)?\.?$")
 DECL_SOME = re.compile(r"^Declaration?:\s*$")
 OUT_SOME = re.compile(r"^Outputs?:\s*$")
 EXAMPLE_IN = re.compile(r"^Example [iI]nputs?:\s*$")
@@ -159,6 +161,7 @@ class Parsing(Enum):
     description, decl, inputs, outputs = "", "", "", ""
     done_desc = False
     no_inputs = False
+    member_var = False
     examples = []
     cur_ex_in = None
     old_names = []
@@ -194,6 +197,9 @@ class Parsing(Enum):
                 error("found multiple Inputs:")
             inputs, no_inputs, mode = MD_NO_INPUT, True, Parsing.NONE
 
+        elif re.search(MEMBER_VAR, line):
+            member_var, no_inputs, mode = True, True, Parsing.DESC
+
         elif re.search(DECL_SOME, line):
             if inputs:
                 error("found multiple Syntax:")
@@ -285,7 +291,7 @@ class Parsing(Enum):
     # We hit the end of the commented section
     if not description or inputs.isspace():
         problems.append("endpoint has no description")
-    if not inputs or inputs.isspace():
+    if (not inputs or inputs.isspace()) and not member_var:
         problems.append(
             "endpoint has no inputs description; perhaps you need to add 'Inputs: none.'?"
         )
@@ -321,7 +327,9 @@ class Parsing(Enum):
 {MD_DECL_HEADER}
 
 {decl}
-
+"""
+    if not member_var:
+        md = md + f"""
 {MD_INPUT_HEADER}
 
 {inputs}

docs/api/static/sidebar.md

@@ -4,6 +4,7 @@
 - [Convo Info Volatile](convo_info_volatile.md)
 - [Encrypt](encrypt.md)
 - [Error](error.md)
+- [Groups](groups.md)
 - [User Groups](user_groups.md)
 - [User Profile](user_profile.md)
 - [Utils](util.md)

include/session/config/base.h

@@ -486,6 +486,8 @@ LIBSESSION_EXPORT void config_set_sig_pubkey(config_object* conf, const unsigned
 /// Returns a pointer to the 32-byte Ed25519 signing pubkey, if set.  Returns nullptr if there is no
 /// current signing pubkey.
 ///
+/// Inputs: none.
+///
 /// Outputs:
 /// - pointer to the 32-byte pubkey, or NULL if not set.
 LIBSESSION_EXPORT const unsigned char* config_get_sig_pubkey(const config_object* conf);

include/session/config/base.hpp

@@ -119,6 +119,8 @@ class ConfigSig {
     ///
     /// Returns a const reference to the 32-byte Ed25519 signing pubkey, if set.
     ///
+    /// Inputs: none.
+    ///
     /// Outputs:
     /// - reference to the 32-byte pubkey, or `std::nullopt` if not set.
     const std::optional<std::array<unsigned char, 32>>& get_sig_pubkey() const { return _sign_pk; }

include/session/config/groups/info.hpp

@@ -261,6 +261,8 @@ class Info final : public ConfigBase {
     /// Returns true if this group has been marked destroyed; the receiving client is expected to
     /// delete it.
     ///
+    /// Inputs: none.
+    ///
     /// Outputs:
     /// - `true` if the group has been destroyed, `false` otherwise.
     bool is_destroyed() const;

include/session/config/groups/keys.hpp

@@ -185,6 +185,8 @@ class Keys final : public ConfigSig {
     /// This isn't typically directly needed: this object manages the key lists in the `info` and
     /// `members` objects itself.
     ///
+    /// Inputs: none.
+    ///
     /// Outputs:
     /// - `std::vector<ustring_view>` - vector of encryption keys.
     std::vector<ustring_view> group_keys() const;
@@ -336,8 +338,9 @@ class Keys final : public ConfigSig {
     ///
     /// Inputs: None
     ///
-    /// Outputs: opaque binary data containing the group keys and other Keys config data that can be
-    /// passed to the `Keys` constructor to reinitialize a Keys object with the current state.
+    /// Outputs:
+    /// - opaque binary data containing the group keys and other Keys config data that can be passed
+    ///   to the `Keys` constructor to reinitialize a Keys object with the current state.
     ustring dump();
 };
 

include/session/config/groups/members.hpp

@@ -45,24 +45,32 @@ struct member {
 
     /// API: groups/member::session_id
     ///
+    /// Member variable
+    ///
     /// The member's session ID, in hex.
     std::string session_id;
 
     /// API: groups/member::name
     ///
+    /// Member variable
+    ///
     /// The member's human-readable name.  Optional.  This is used by other members of the group to
     /// display a member's details before having seen a message from that member.
     std::string name;
 
     /// API: groups/member::profile_picture
     ///
+    /// Member variable
+    ///
     /// The member's profile picture (URL & decryption key).  Optional.  This is used by other
     /// members of the group to display a member's details before having seen a message from that
     /// member.
     profile_pic profile_picture;
 
     /// API: groups/member::admin
     ///
+    /// Member variable
+    ///
     /// Flag that is set to indicate to the group that this member is an admin.
     ///
     /// Note that this is only informative but isn't a permission gate: someone could still possess
@@ -83,19 +91,27 @@ struct member {
     /// to the group.  The optional `failed` parameter can be specified as true if the invitation
     /// was issued but failed to send for some reason (this is intended as a signal to other clients
     /// that the invitation should be reissued).
+    ///
+    /// Inputs:
+    /// - `failed` can be specified and set to `true` to the invite status to "failed-to-send";
+    ///   otherwise omitting it or giving as `false` sets the invite status to "sent."
     void set_invited(bool failed = false) { invite_status = failed ? INVITE_FAILED : INVITE_SENT; }
 
     /// API: groups/members::set_accepted
     ///
     /// This clears the "invited" flag for this user, thus indicating that the user has accepted an
     /// invitation and is now a regular member of the group.
+    ///
+    /// Inputs: none
     void set_accepted() { invite_status = 0; }
 
     /// API: groups/member::invite_pending
     ///
     /// Returns whether the user currently has a pending invitation.  Returns true if so (whether or
     /// not that invitation has failed).
     ///
+    /// Inputs: none
+    ///
     /// Outputs:
     /// - `bool` -- true if the user has a pending invitation, false otherwise.
     bool invite_pending() const { return invite_status > 0; }
@@ -105,6 +121,8 @@ struct member {
     /// Returns true if the user has a pending invitation that is marked as failed (and thus should
     /// be re-sent).
     ///
+    /// Inputs: none
+    ///
     /// Outputs:
     /// - `bool` -- true if the user has a failed pending invitation
     bool invite_failed() const { return invite_status == INVITE_FAILED; }
@@ -121,6 +139,10 @@ struct member {
     /// to other clients that the promotion should be reissued).
     ///
     /// Note that this flag is ignored when the `admin` field is set to true.
+    ///
+    /// Inputs:
+    /// - `failed`: can be specified as true to mark the promotion status as "failed-to-send".  If
+    ///   omitted or false then the promotion status is set to "sent".
     void set_promoted(bool failed = false) {
         promotion_status = failed ? INVITE_FAILED : INVITE_SENT;
     }
@@ -130,6 +152,8 @@ struct member {
     /// Returns whether the user currently has a pending invitation/promotion to admin status.
     /// Returns true if so (whether or not that invitation has failed).
     ///
+    /// Inputs: None
+    ///
     /// Outputs:
     /// - `bool` -- true if the user has a pending promotion, false otherwise.
     bool promotion_pending() const { return !admin && promotion_status > 0; }
@@ -139,13 +163,20 @@ struct member {
     /// Returns true if the user has a pending promotion-to-admin that is marked as failed (and thus
     /// should be re-sent).
     ///
+    /// Inputs: None
+    ///
     /// Outputs:
     /// - `bool` -- true if the user has a failed pending promotion
     bool promotion_failed() const { return !admin && promotion_status == INVITE_FAILED; }
 
     /// API: groups/member::promoted
     ///
     /// Returns true if the user is already an admin *or* has a pending promotion to admin.
+    ///
+    /// Inputs: none.
+    ///
+    /// Outputs:
+    /// - `bool` -- true if the member is promoted (or promotion-in-progress)
     bool promoted() const { return admin || promotion_pending(); }
 
     /// API: groups/member::info