From f594be6eb5e22b6e48db8f14c5ee82364e3427e6 Mon Sep 17 00:00:00 2001 From: Sam Andreae Date: Tue, 31 May 2022 17:55:00 +0100 Subject: [PATCH] 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 --- aquadoggo/src/db/models/entry.rs | 3 ++- aquadoggo/src/db/models/log.rs | 6 ++---- aquadoggo/src/db/stores/entry.rs | 21 ++++++++++++++++++--- aquadoggo/src/db/stores/log.rs | 13 ++++++++++++- 4 files changed, 34 insertions(+), 9 deletions(-) diff --git a/aquadoggo/src/db/models/entry.rs b/aquadoggo/src/db/models/entry.rs index 9504e61a6..f34d7d92f 100644 --- a/aquadoggo/src/db/models/entry.rs +++ b/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. diff --git a/aquadoggo/src/db/models/log.rs b/aquadoggo/src/db/models/log.rs index fed30b6bb..7f84135cd 100644 --- a/aquadoggo/src/db/models/log.rs +++ b/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. diff --git a/aquadoggo/src/db/stores/entry.rs b/aquadoggo/src/db/stores/entry.rs index 2eceb8b67..8f9c02f94 100644 --- a/aquadoggo/src/db/stores/entry.rs +++ b/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 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 for SqlStorage { /// Insert an entry into storage. diff --git a/aquadoggo/src/db/stores/log.rs b/aquadoggo/src/db/stores/log.rs index c044e5e91..aaf9a15b1 100644 --- a/aquadoggo/src/db/stores/log.rs +++ b/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 for SqlStorage { /// Insert a log into storage.