From 8466510fee7046a5fee120e28ab044c27f2bba0c Mon Sep 17 00:00:00 2001 From: glyph Date: Mon, 14 Feb 2022 17:00:00 +0200 Subject: [PATCH] polish the message type docs --- src/messages.rs | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/src/messages.rs b/src/messages.rs index 7a52a6a..c26da6e 100644 --- a/src/messages.rs +++ b/src/messages.rs @@ -7,14 +7,17 @@ use std::fmt::Debug; use crate::error::GolgiError; -/// This is an alias to TypedMessage in kuska, -/// which is renamed as SsbMessageContent in golgi to fit the naming convention -/// of the other types (SsbMessageKVT and SsbMessageValue) +/// `SsbMessageContent` is a type alias for `TypedMessage` from the `kuska_ssb` library. +/// It is aliased in golgi to fit the naming convention of the other message +/// types: `SsbMessageKVT` and `SsbMessageValue`. +/// +/// See the [kuska source code](https://github.com/Kuska-ssb/ssb/blob/master/src/api/dto/content.rs#L103) for the type definition of `TypedMessage`. pub type SsbMessageContent = TypedMessage; -/// Data type representing the `value` of a message object (`KVT`). More information concerning the -/// data model can be found -/// in the [`Metadata` documentation](https://spec.scuttlebutt.nz/feed/messages.html#metadata). +/// The `value` of an SSB message (the `V` in `KVT`). +/// +/// More information concerning the data model can be found in the +/// [`Metadata` documentation](https://spec.scuttlebutt.nz/feed/messages.html#metadata). #[derive(Serialize, Deserialize, Debug)] #[serde(deny_unknown_fields)] #[allow(missing_docs)] @@ -28,7 +31,7 @@ pub struct SsbMessageValue { pub signature: String, } -// Enum representing the different possible message content types +/// Message content types. #[derive(Debug)] #[allow(missing_docs)] pub enum SsbMessageContentType { @@ -40,9 +43,13 @@ pub enum SsbMessageContentType { } impl SsbMessageValue { - /// Gets the type field of the message content as an enum, if found. - /// if no type field is found or the type field is not a string, it returns an Err(GolgiError::ContentType) - /// if a type field is found but with an unknown string it returns an Ok(SsbMessageContentType::Unrecognized) + /// Get the type field of the message content as an enum, if found. + /// + /// If no `type` field is found or the `type` field is not a string, + /// it returns an `Err(GolgiError::ContentType)`. + /// + /// If a `type` field is found but with an unknown string, + /// it returns an `Ok(SsbMessageContentType::Unrecognized)`. pub fn get_message_type(&self) -> Result { let msg_type = self .content @@ -61,8 +68,8 @@ impl SsbMessageValue { Ok(enum_type) } - /// Helper function which returns true if this message is of the given type, - /// and false if the type does not match or is not found + /// Helper function which returns `true` if this message is of the given type, + /// and `false` if the type does not match or is not found. pub fn is_message_type(&self, _message_type: SsbMessageContentType) -> bool { let self_message_type = self.get_message_type(); match self_message_type { @@ -73,8 +80,8 @@ impl SsbMessageValue { } } - /// Converts the content json value into an SsbMessageContent enum, - /// using the "type" field as a tag to select which variant of the enum + /// Convert the content JSON value into an `SsbMessageContent` `enum`, + /// using the `type` field as a tag to select which variant of the `enum` /// to deserialize into. /// /// See the [Serde docs on internally-tagged enum representations](https://serde.rs/enum-representations.html#internally-tagged) for further details. @@ -84,9 +91,10 @@ impl SsbMessageValue { } } -/// Data type representing the `value` of a message object (`KVT`). More information concerning the -/// data model can be found -/// in the [`Metadata` documentation](https://spec.scuttlebutt.nz/feed/messages.html#metadata). +/// An SSB message represented as a key-value-timestamp (`KVT`). +/// +/// More information concerning the data model can be found in the +/// [`Metadata` documentation](https://spec.scuttlebutt.nz/feed/messages.html#metadata). #[derive(Serialize, Deserialize, Debug)] #[serde(deny_unknown_fields)] #[allow(missing_docs)]