docs: documents sources interfaces documentation

Author: damian-molinski

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/document/source/document_data_local_source.dart

@@ -1,22 +1,45 @@
 import 'package:catalyst_voices_models/catalyst_voices_models.dart';
 import 'package:catalyst_voices_repositories/catalyst_voices_repositories.dart';
 
-/// Base interface to interact with locally document data.
+/// Base interface to interact with locally stored document data (Database/Storage).
+///
+/// This interface handles common CRUD operations and reactive streams for
+/// both [SignedDocumentDataSource] and [DraftDataSource].
 abstract interface class DocumentDataLocalSource implements DocumentDataSource {
+  /// Counts the number of documents matching the provided filters.
+  ///
+  /// * [type]: Filter by the [DocumentType] (e.g., Proposal, Comment).
+  /// * [ref]: Filter by the specific identity of the document (ID/Version).
+  /// * [refTo]: Filter for documents that reference *this* target [refTo].
+  ///   (e.g., Find all comments pointing to Proposal X).
   Future<int> count({
     DocumentType? type,
     DocumentRef? ref,
     DocumentRef? refTo,
   });
 
+  /// Deletes documents matching the provided filters.
+  ///
+  /// * [typeNotIn]: If provided, deletes all documents *except* those
+  ///   matching the types in this list.
+  ///
+  /// Returns the number of records deleted.
   Future<int> delete({
     List<DocumentType>? typeNotIn,
   });
 
+  /// Checks if a specific document exists in local storage.
   Future<bool> exists({required DocumentRef ref});
 
+  /// Checks a list of [refs] and returns a subset list containing only
+  /// the references that actually exist in the local storage.
   Future<List<DocumentRef>> filterExisting(List<DocumentRef> refs);
 
+  /// Retrieves a list of documents matching the provided filters.
+  ///
+  /// * [latestOnly]: If `true`, only the most recent version of each
+  ///   document ID is returned.
+  /// * [limit] and [offset]: Used for pagination.
   Future<List<DocumentData>> getAll({
     DocumentType? type,
     DocumentRef? ref,
@@ -26,22 +49,36 @@ abstract interface class DocumentDataLocalSource implements DocumentDataSource {
     int offset,
   });
 
+  /// Retrieves a single document matching the provided filters.
+  ///
+  /// Returns `null` if no document matches or if multiple match (depending on impl).
+  /// Generally used when the filter is expected to yield a unique result.
   Future<DocumentData?> getWhere({
     DocumentType? type,
     DocumentRef? ref,
     DocumentRef? refTo,
   });
 
+  /// Persists a single [DocumentData] object to local storage.
+  ///
+  /// If the document already exists, it should be updated (upsert).
   Future<void> save({required DocumentData data});
 
+  /// Persists multiple [DocumentData] objects to local storage in a batch.
   Future<void> saveAll(Iterable<DocumentData> data);
 
+  /// Watches for changes to a single document matching the filters.
+  ///
+  /// Emits a new value whenever the matching document is updated or inserted.
   Stream<DocumentData?> watch({
     DocumentType? type,
     DocumentRef? ref,
     DocumentRef? refTo,
   });
 
+  /// Watches for changes to a list of documents matching the filters.
+  ///
+  /// Emits a new list whenever any document matching the criteria changes.
   Stream<List<DocumentData>> watchAll({
     DocumentType? type,
     DocumentRef? ref,
@@ -51,6 +88,7 @@ abstract interface class DocumentDataLocalSource implements DocumentDataSource {
     int offset,
   });
 
+  /// Watches the count of documents matching the filters.
   Stream<int> watchCount({
     DocumentType? type,
     DocumentRef? ref,

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/document/source/document_data_source.dart

@@ -1,7 +1,17 @@
 import 'package:catalyst_voices_models/catalyst_voices_models.dart';
 
+/// A base interface for retrieving document data from any source (Local, Remote, Memory).
 abstract interface class DocumentDataSource {
+  /// Retrieves a specific document by its unique reference.
+  ///
+  /// Returns `null` if the document with the specific [DocumentRef.id] and
+  /// [DocumentRef.version] is not found.
   Future<DocumentData?> get(DocumentRef ref);
 
+  /// Resolves the reference to the latest available version of a document chain.
+  ///
+  /// If [ref] points to an older version, this returns the [DocumentRef]
+  /// for the most recent version of that document ID.
+  /// Returns `null` if the document ID does not exist in the source.
   Future<DocumentRef?> getLatestRefOf(DocumentRef ref);
 }

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/document/source/local_document_data_local_source.dart

@@ -1,14 +1,25 @@
 import 'package:catalyst_voices_models/catalyst_voices_models.dart';
 import 'package:catalyst_voices_repositories/catalyst_voices_repositories.dart';
 
+/// Interface for accessing mutable draft documents.
+///
+/// Drafts are local-only, unsigned work-in-progress documents.
 /// See [DatabaseDraftsDataSource].
 abstract interface class DraftDataSource implements DocumentDataLocalSource {
+  /// Deletes drafts matching the criteria.
+  ///
+  /// * [ref]: If provided, deletes the specific draft.
+  /// * [typeNotIn]: Deletes all drafts NOT matching these types (often used for cleanup).
   @override
   Future<int> delete({
     DocumentRef? ref,
     List<DocumentType>? typeNotIn,
   });
 
+  /// Updates the content of an existing draft identified by [ref].
+  ///
+  /// This is distinct from [save] as it implies modifying the payload
+  /// of an existing entity without necessarily creating a new version/ID.
   Future<void> update({
     required DraftRef ref,
     required DocumentDataContent content,

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/document/source/signed_document_data_local_source.dart

@@ -1,8 +1,15 @@
 import 'package:catalyst_voices_models/catalyst_voices_models.dart';
 import 'package:catalyst_voices_repositories/catalyst_voices_repositories.dart';
 
+/// Interface for accessing immutable, cryptographically signed documents.
+///
+/// Signed documents are final and cannot be modified, only superseded by
+/// newer versions.
 /// See [DatabaseDocumentsDataSource].
 abstract interface class SignedDocumentDataSource implements DocumentDataLocalSource {
+  /// Retrieves a single signed document matching the filters.
+  ///
+  /// * [authorId]: Filters documents authored by a specific [CatalystId].
   @override
   Future<DocumentData?> getWhere({
     DocumentType? type,
@@ -11,6 +18,9 @@ abstract interface class SignedDocumentDataSource implements DocumentDataLocalSo
     CatalystId? authorId,
   });
 
+  /// Watches for changes to a list of signed documents.
+  ///
+  /// * [authorId]: Filters documents authored by a specific [CatalystId].
   @override
   Stream<List<DocumentData>> watchAll({
     DocumentType? type,