add features and extend example usage section

src/lib.rs

@@ -2,24 +2,68 @@
 
 //! # golgi
 //!
-//! _The Golgi complex (aka. Golgi apparatus or Golgi body) packages proteins into membrane-bound vesicles inside the cell before the vesicles are sent to their destination._
+//! _The Golgi complex (aka. Golgi apparatus or Golgi body) packages proteins
+//! into membrane-bound vesicles inside the cell before the vesicles are sent
+//! to their destination._
 //!
 //! -----
 //!
-//! Golgi is an experimental Scuttlebutt client which uses the [kuska-ssb](https://github.com/Kuska-ssb) libraries and aims to provide a high-level API for interacting with an sbot instance. Development efforts are currently oriented towards [go-sbot](https://github.com/cryptoscope/ssb) interoperability.
+//! ## Introduction
+//!
+//! Golgi is an experimental Scuttlebutt client which uses the
+//! [kuska-ssb](https://github.com/Kuska-ssb) libraries and aims to provide a
+//! high-level API for interacting with an sbot instance. Development efforts
+//! are currently oriented towards [go-sbot](https://github.com/cryptoscope/ssb)
+//! interoperability.
+//!
+//! The primary means of interacting with the `golgi` library is the
+//! [`Sbot`](crate::sbot::Sbot) `struct`. `Sbot` offers the ability to connect
+//! to an sbot instance and exposes a number of RPC and convenience methods.
+//!
+//! ## Features
+//!
+//! `golgi` offers the ability to invoke individual RPC methods while also
+//! providing a number of convenience methods which may involve multiple RPC
+//! calls and / or the processing of data received from those calls.
+//!
+//! Features include the ability to publish messages of various kinds; to
+//! retrieve messages (e.g. `about` and `description` messages) and formulate
+//! queries; to follow, unfollow, block and unblock a peers; to query the social
+//! graph; and to generate pub invite codes.
 //!
 //! ## Example Usage
 //!
+//! Basic usage is demonstrated below. Visit the [examples directory](https://git.coopcloud.tech/golgi-ssb/golgi/src/branch/main/examples) in the `golgi` repository for
+//! more comprehensive examples.
+//!
 //! ```rust
 //! use golgi::GolgiError;
 //! use golgi::sbot::Sbot;
 //!
 //! pub async fn run() -> Result<(), GolgiError> {
+//!     // Attempt to connect to an sbot instance using the default IP address,
+//!     // port and network key (aka. capabilities key).
 //!     let mut sbot_client = Sbot::connect(None, None).await?;
 //!
+//!     // Call the `whoami` RPC method to retrieve the public key for the sbot
+//!     // identity.
 //!     let id = sbot_client.whoami().await?;
+//!     
+//!     // Print the public key (identity) to `stdout`.
 //!     println!("{}", id);
 //!
+//!     // Compose an SSB post message type.
+//!     let post = SsbMessageContent::Post {
+//!         text: "Biology, eh?!".to_string(),
+//!         mentions: None,
+//!     };
+//!
+//!     // Publish the post.
+//!     let post_msg_reference = sbot_client.publish(post).await?;
+//!
+//!     // Print the reference (sigil-link) for the published post.
+//!     println!("{}", post_msg_reference);
+//!
 //!     Ok(())
 //! }
 //! ```