Doc strings for entry and log store structs (#126)

* Doc strings for entry store structs

* Doc strings for LogStore structs

* Doc strings for row structs

* Fix import ordering

* Minor typo fix

Co-authored-by: Andreas Dzialocha <x12@adz.garden>

aquadoggo/src/db/models/entry.rs

@@ -3,7 +3,8 @@
 use serde::Serialize;
 use sqlx::FromRow;
 
-/// Struct representing the actual SQL row of `Entry`.
+/// Representation of a row from the entries table as stored in the database. This is required
+/// when coercing the returned results from a query with the `sqlx` library.
 ///
 /// We store the u64 integer values of `log_id` and `seq_num` as strings since SQLite doesn't
 /// support storing unsigned 64 bit integers.

aquadoggo/src/db/models/log.rs

@@ -2,10 +2,8 @@
 
 use sqlx::FromRow;
 
-/// Tracks the assigment of an author's logs to documents and records their schema.
-///
-/// This serves as an indexing layer on top of the lower-level bamboo entries. The node updates
-/// this data according to what it sees in the newly incoming entries.
+/// Representation of a row from the logs table as stored in the database. This is required
+/// when coercing the returned results from a query with the `sqlx` library.
 ///
 /// We store the u64 integer values of `log_id` as a string here since SQLite doesn't support
 /// storing unsigned 64 bit integers.

aquadoggo/src/db/stores/entry.rs

@@ -2,8 +2,6 @@
 
 use async_trait::async_trait;
 use lipmaa_link::get_lipmaa_links_back_to;
-use p2panda_rs::storage_provider::ValidationError;
-use p2panda_rs::Validate;
 use sqlx::{query, query_as};
 
 use p2panda_rs::entry::{decode_entry, Entry, EntrySigned, LogId, SeqNum};
@@ -13,10 +11,19 @@ use p2panda_rs::operation::{Operation, OperationEncoded};
 use p2panda_rs::schema::SchemaId;
 use p2panda_rs::storage_provider::errors::EntryStorageError;
 use p2panda_rs::storage_provider::traits::{AsStorageEntry, EntryStore};
+use p2panda_rs::storage_provider::ValidationError;
+use p2panda_rs::Validate;
 
 use crate::db::models::EntryRow;
 use crate::db::provider::SqlStorage;
 
+/// A signed entry and it's encoded operation. Entries are the lowest level data
+/// type on the p2panda network, they are signed by authors and form bamboo append
+/// only logs. The operation is an entries' payload, it contains the data mutations
+/// which authors publish.
+///
+/// This struct implements the `AsStorageEntry` trait which is required when
+/// constructing the `EntryStore`.
 #[derive(Debug, Clone, PartialEq)]
 pub struct StorageEntry {
     entry_signed: EntrySigned,
@@ -51,6 +58,9 @@ impl Validate for StorageEntry {
     }
 }
 
+/// `From` implementation for converting an `EntryRow` into a `StorageEntry`. This is useful
+/// when retrieving entries from the database. The `sqlx` crate coerces returned entry rows
+/// into `EntryRow` but we normally want them as `StorageEntry`.
 impl From<EntryRow> for StorageEntry {
     fn from(entry_row: EntryRow) -> Self {
         // Unwrapping everything here as we assume values coming from the database are valid.
@@ -112,7 +122,12 @@ impl AsStorageEntry for StorageEntry {
     }
 }
 
-/// Trait which handles all storage actions relating to `Entries`.
+/// Implementation of `EntryStore` trait which is required when constructing a
+/// `StorageProvider`.
+///
+/// Handles storage and retrieval of entries in the form of`StorageEntry` which
+/// implements the required `AsStorageEntry` trait. An intermediary struct `EntryRow`
+/// is also used when retrieving an entry from the database.
 #[async_trait]
 impl EntryStore<StorageEntry> for SqlStorage {
     /// Insert an entry into storage.

aquadoggo/src/db/stores/log.rs

@@ -12,6 +12,12 @@ use p2panda_rs::storage_provider::traits::{AsStorageLog, LogStore};
 
 use crate::db::provider::SqlStorage;
 
+/// Tracks the assigment of an author's logs to documents and records their schema.
+///
+/// This serves as an indexing layer on top of the lower-level bamboo entries. The node updates
+/// this data according to what it sees in the newly incoming entries.
+///
+/// `StorageLog` implements the trait `AsStorageLog` which is required when defining a `LogStore`.
 pub struct StorageLog {
     author: Author,
     log_id: LogId,
@@ -51,7 +57,12 @@ impl AsStorageLog for StorageLog {
     }
 }
 
-/// Trait which handles all storage actions relating to `StorageLog`s.
+/// Implementation of `LogStore` trait which is required when constructing a
+/// `StorageProvider`.
+///
+/// Handles storage and retrieval of logs in the form of `StorageLog` which
+/// implements the required `AsStorageLog` trait. An intermediary struct `LogRow`
+/// is also used when retrieving a log from the database.
 #[async_trait]
 impl LogStore<StorageLog> for SqlStorage {
     /// Insert a log into storage.