docs: function/struct comments

src/close.rs

@@ -1,4 +1,6 @@
 //! Subscription close request parsing
+//!
+//! Representation and parsing of `CLOSE` messages sent from clients.
 use crate::error::{Error, Result};
 use serde::{Deserialize, Serialize};
 
@@ -11,7 +13,7 @@ pub struct CloseCmd {
     id: String,
 }
 
-/// Close command parsed
+/// Identifier of the subscription to be closed.
 #[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
 pub struct Close {
     /// The subscription identifier being closed.

src/db.rs

@@ -126,6 +126,7 @@ FOREIGN KEY(metadata_event) REFERENCES event(id) ON UPDATE CASCADE ON DELETE CAS
 
 // TODO: drop the pubkey_ref and event_ref tables
 
+/// Build a database connection pool.
 pub fn build_pool(
     name: &str,
     flags: OpenFlags,
@@ -469,13 +470,14 @@ pub async fn db_writer(
     })
 }
 
+/// Determine the current application database schema version.
 pub fn db_version(conn: &mut Connection) -> Result<usize> {
     let query = "PRAGMA user_version;";
     let curr_version = conn.query_row(query, [], |row| row.get(0))?;
     Ok(curr_version)
 }
 
-/// Persist an event to the database.
+/// Persist an event to the database, returning rows added.
 pub fn write_event(conn: &mut PooledConnection, e: &Event) -> Result<usize> {
     // start transaction
     let tx = conn.transaction()?;
@@ -549,7 +551,7 @@ pub fn write_event(conn: &mut PooledConnection, e: &Event) -> Result<usize> {
     Ok(ins_count)
 }
 
-/// Event resulting from a specific subscription request
+/// Serialized event associated with a specific subscription request.
 #[derive(PartialEq, Debug, Clone)]
 pub struct QueryResult {
     /// Subscription identifier
@@ -568,6 +570,7 @@ fn is_all_fs(s: &str) -> bool {
     s.chars().all(|x| x == 'f' || x == 'F')
 }
 
+/// Types of hexadecimal queries.
 #[derive(PartialEq, Debug, Clone)]
 enum HexSearch {
     // when no range is needed, exact 32-byte
@@ -637,6 +640,7 @@ fn hex_range(s: &str) -> Option<HexSearch> {
     Some(HexSearch::Range(base, upper))
 }
 
+/// Produce a arbitrary list of '?' parameters.
 fn repeat_vars(count: usize) -> String {
     if count == 0 {
         return "".to_owned();

src/event.rs

@@ -16,17 +16,18 @@ use std::str::FromStr;
 use std::time::SystemTime;
 
 lazy_static! {
+    /// Secp256k1 verification instance.
     pub static ref SECP: Secp256k1<VerifyOnly> = Secp256k1::verification_only();
 }
 
-/// Event command in network format
+/// Event command in network format.
 #[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
 pub struct EventCmd {
     cmd: String, // expecting static "EVENT"
     event: Event,
 }
 
-/// Event parsed
+/// Parsed nostr event.
 #[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
 pub struct Event {
     pub id: String,
@@ -71,7 +72,7 @@ impl From<EventCmd> for Result<Event> {
     }
 }
 
-/// Seconds since 1970
+/// Seconds since 1970.
 pub fn unix_time() -> u64 {
     SystemTime::now()
         .duration_since(SystemTime::UNIX_EPOCH)

src/lib.rs

@@ -8,4 +8,3 @@ pub mod info;
 pub mod nip05;
 pub mod protostream;
 pub mod subscription;
-pub mod tags;

src/nip05.rs

@@ -1,4 +1,9 @@
 //! User verification using NIP-05 names
+//!
+//! NIP-05 defines a mechanism for authors to associate an internet
+//! address with their public key, in metadata events.  This module
+//! consumes a stream of metadata events, and keeps a database table
+//! updated with the current NIP-05 verification status.
 use crate::config::SETTINGS;
 use crate::db;
 use crate::error::{Error, Result};
@@ -15,7 +20,7 @@ use std::time::Instant;
 use std::time::SystemTime;
 use tokio::time::Interval;
 
-/// NIP-05 verifier
+/// NIP-05 verifier state
 pub struct Verifier {
     /// Metadata events for us to inspect
     metadata_rx: tokio::sync::broadcast::Receiver<Event>,
@@ -649,8 +654,7 @@ pub async fn save_verification_record(
     }).await?
 }
 
-/// Retrieve the most recent verification record for a given pubkey
+/// Retrieve the most recent verification record for a given pubkey (async).
-// Important, this is the most recent verification /of the most recent metadata event/.
 pub async fn get_latest_user_verification(
     conn: db::PooledConnection,
     pubkey: &str,
@@ -659,6 +663,7 @@ pub async fn get_latest_user_verification(
     tokio::task::spawn_blocking(move || query_latest_user_verification(conn, p)).await?
 }
 
+/// Query database for the latest verification record for a given pubkey.
 pub fn query_latest_user_verification(
     mut conn: db::PooledConnection,
     pubkey: String,