add doc comment examples for publish api

src/api/publish.rs

@@ -10,13 +10,34 @@
 use crate::{error::GolgiError, messages::SsbMessageContent, sbot::Sbot, utils};
 
 impl Sbot {
-    /// Call the `publish` RPC method and return a message reference.
+    /// Publish a message.
     ///
     /// # Arguments
     ///
-    /// * `msg` - A `SsbMessageContent` `enum` whose variants include `Pub`, `Post`, `Contact`, `About`,
+    /// * `msg` - A `SsbMessageContent` `enum` whose variants include `Pub`,
-    /// `Channel` and `Vote`. See the `kuska_ssb` documentation for further details such as field
+    /// `Post`, `Contact`, `About`, `Channel` and `Vote`.
-    /// names and accepted values for each variant.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use golgi::{Sbot, GolgiError, messages::SsbMessageContent};
+    ///
+    /// async fn publish_a_msg() -> Result<(), GolgiError> {
+    ///     let mut sbot_client = Sbot::init(None, None).await?;
+    ///
+    ///     // Construct an SSB message of type `post`.
+    ///     let post = SsbMessageContent::Post {
+    ///         text: "And then those vesicles, filled with the Golgi products, move to the rest of the cell".to_string(),
+    ///         mentions: None,
+    ///     };
+    ///
+    ///     let msg_ref = sbot_client.publish(post).await?;
+    ///
+    ///     println!("msg reference for the golgi post: {}", msg_ref);
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub async fn publish(&mut self, msg: SsbMessageContent) -> Result<String, GolgiError> {
         let mut sbot_connection = self.get_sbot_connection().await?;
         let req_id = sbot_connection.client.publish_req_send(msg).await?;
@@ -29,11 +50,28 @@ impl Sbot {
         .await
     }
 
-    /// Wrapper for publish which constructs and publishes a post message appropriately from a string.
+    /// Publish a post.
     ///
-    /// # Arguments
+    /// Convenient wrapper around the `publish` method which constructs and
+    /// publishes a `post` type message appropriately from a string.
     ///
-    /// * `text` - A reference to a string slice which represents the text to be published in the post
+    /// # Example
+    ///
+    /// ```rust
+    /// use golgi::{Sbot, GolgiError};
+    ///
+    /// async fn publish_a_post() -> Result<(), GolgiError> {
+    ///     let mut sbot_client = Sbot::init(None, None).await?;
+    ///
+    ///     let text = "The Golgi is located right near the nucleus.";
+    ///
+    ///     let msg_ref = sbot_client.publish_post(text).await?;
+    ///
+    ///     println!("msg reference for the golgi post: {}", msg_ref);
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub async fn publish_post(&mut self, text: &str) -> Result<String, GolgiError> {
         let msg = SsbMessageContent::Post {
             text: text.to_string(),
@@ -42,11 +80,28 @@ impl Sbot {
         self.publish(msg).await
     }
 
-    /// Wrapper for publish which constructs and publishes an about description message appropriately from a string.
+    /// Publish a description for the local identity.
     ///
-    /// # Arguments
+    /// Convenient wrapper around the `publish` method which constructs and
+    /// publishes an `about` type description message appropriately from a string.
     ///
-    /// * `description` - A reference to a string slice which represents the text to be published as an about description.
+    /// # Example
+    ///
+    /// ```rust
+    /// use golgi::{Sbot, GolgiError};
+    ///
+    /// async fn publish_a_description() -> Result<(), GolgiError> {
+    ///     let mut sbot_client = Sbot::init(None, None).await?;
+    ///
+    ///     let description = "The Golgi apparatus was identified by the Italian scientist Camillo Golgi in 1897.";
+    ///
+    ///     let msg_ref = sbot_client.publish_description(description).await?;
+    ///
+    ///     println!("msg reference for the golgi description: {}", msg_ref);
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub async fn publish_description(&mut self, description: &str) -> Result<String, GolgiError> {
         let msg = SsbMessageContent::About {
             about: self.id.to_string(),
@@ -61,11 +116,28 @@ impl Sbot {
         self.publish(msg).await
     }
 
-    /// Wrapper for publish which constructs and publishes an about name message appropriately from a string.
+    /// Publish a name for the local identity.
     ///
-    /// # Arguments
+    /// Convenient wrapper around the `publish` method which constructs and
+    /// publishes an `about` type name message appropriately from a string.
     ///
-    /// * `name` - A reference to a string slice which represents the text to be published as an about name.
+    /// # Example
+    ///
+    /// ```rust
+    /// use golgi::{Sbot, GolgiError};
+    ///
+    /// async fn publish_a_name() -> Result<(), GolgiError> {
+    ///     let mut sbot_client = Sbot::init(None, None).await?;
+    ///
+    ///     let name = "glyphski_golgionikus";
+    ///
+    ///     let msg_ref = sbot_client.publish_name(name).await?;
+    ///
+    ///     println!("msg reference: {}", msg_ref);
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub async fn publish_name(&mut self, name: &str) -> Result<String, GolgiError> {
         let msg = SsbMessageContent::About {
             about: self.id.to_string(),