docs: document categories of API elements

packages/cbl/README.md

@@ -11,7 +11,7 @@
 - Data is stored in JSON documents
   - Schemaless
   - Stored in efficient binary format
-  - Support storing binary blobs
+  - Supports storing of binary blobs
 - Queries
   - Construct queries through a type safe builder API or write them in [N1QL]
   - Rich query language, supporting complex queries
@@ -21,7 +21,7 @@
   - Synchronize with Couchbase Server through Sync Gateway
   - Local conflict resolution
   - Replication between two local databases\*
-  - Use document deltas to transfer changes\*
+  - Transfer document changes as deltas\*
 - Change observer APIs for:
   - Database
   - Query

packages/cbl/dartdoc_options.yaml

@@ -2,4 +2,24 @@ dartdoc:
   categories:
     'Enterprise Edition':
       markdown: 'doc/enterprise-edition.md'
-  categoryOrder: ['Enterprise Edition']
+    'Document':
+      markdown: 'doc/document.md'
+    'Database':
+      markdown: 'doc/database.md'
+    'Query':
+      markdown: 'doc/query.md'
+    'Query Builder':
+      markdown: 'doc/query-builder.md'
+    'Replication':
+      markdown: 'doc/replication.md'
+    'Logging':
+      markdown: 'doc/logging.md'
+  categoryOrder:
+    - 'Document'
+    - 'Database'
+    - 'Query'
+    - 'Query Builder'
+    - 'Replication'
+    - 'Logging'
+    - 'Enterprise Edition'
+  showUndocumentedCategories: true

packages/cbl/doc/enterprise-edition.md

@@ -1,4 +1,2 @@
-# Enterprise Edition
-
 The Enterprise Edition of Couchbase Lite provides additional features not
 available in the Community Edition.

packages/cbl/lib/src/database/database.dart

@@ -16,6 +16,8 @@ import 'ffi_database.dart';
 import 'proxy_database.dart';
 
 /// Conflict-handling options when saving or deleting a document.
+///
+/// {@category Database}
 enum ConcurrencyControl {
   /// The current save/delete will overwrite a conflicting revision if there is
   /// a conflict.
@@ -26,6 +28,8 @@ enum ConcurrencyControl {
 }
 
 /// The type of maintenance a database can perform.
+///
+/// {@category Database}
 enum MaintenanceType {
   /// Compact the database file and delete unused attachments.
   compact,
@@ -62,19 +66,27 @@ enum MaintenanceType {
 ///
 ///  * [Database.saveDocumentWithConflictHandler] for saving a [Document] with
 ///    a custom async conflict handler.
+///
+/// {@category Database}
 typedef SaveConflictHandler = FutureOr<bool> Function(
   MutableDocument documentBeingSaved,
   Document? conflictingDocument,
 );
 
 /// Listener which is called when one or more [Document]s in a [Database] have
 /// changed.
+///
+/// {@category Database}
 typedef DatabaseChangeListener = void Function(DatabaseChange change);
 
 /// Listener which is called when a single [Document] has changed.
+///
+/// {@category Database}
 typedef DocumentChangeListener = void Function(DocumentChange change);
 
 /// A Couchbase Lite database.
+///
+/// {@category Database}
 abstract class Database implements ClosableResource {
   /// {@template cbl.Database.openAsync}
   /// Opens a Couchbase Lite database with the given [name] and [config],
@@ -384,12 +396,16 @@ abstract class Database implements ClosableResource {
 ///
 ///  * [SyncDatabase.saveDocumentWithConflictHandlerSync] for saving a
 ///    [Document] with a custom sync conflict handler.
+///
+/// {@category Database}
 typedef SyncSaveConflictHandler = bool Function(
   MutableDocument documentBeingSaved,
   Document? conflictingDocument,
 );
 
 /// A [Database] with a primarily synchronous API.
+///
+/// {@category Database}
 abstract class SyncDatabase implements Database {
   /// {@macro cbl.Database.openSync}
   factory SyncDatabase(String name, [DatabaseConfiguration? config]) =>
@@ -491,6 +507,8 @@ abstract class SyncDatabase implements Database {
 }
 
 /// A [Database] with a primarily asynchronous API.
+///
+/// {@category Database}
 abstract class AsyncDatabase implements Database {
   /// {@macro cbl.Database.openAsync}
   static Future<AsyncDatabase> open(

packages/cbl/lib/src/database/database_change.dart

@@ -5,6 +5,8 @@ import '../document.dart';
 import 'database.dart';
 
 /// A [Database] change event.
+///
+/// {@category Database}
 @immutable
 class DatabaseChange {
   /// Creates a [Database] change event.

packages/cbl/lib/src/database/database_configuration.dart

@@ -40,6 +40,7 @@ import 'database.dart';
 ///   - [Database.changeEncryptionKey] for changing the encryption key of a
 ///     [Database].
 ///
+/// {@category Database}
 /// {@category Enterprise Edition}
 abstract class EncryptionKey {
   /// Creates an [EncryptionKey] from raw [bytes].
@@ -132,6 +133,8 @@ class EncryptionKeyImpl implements EncryptionKey {
 }
 
 /// Configuration for opening or copying a [Database].
+///
+/// {@category Database}
 class DatabaseConfiguration {
   /// Creates a configuration for opening or copying a [Database].
   DatabaseConfiguration({String? directory, this.encryptionKey})

packages/cbl/lib/src/database/document_change.dart

@@ -4,6 +4,8 @@ import '../document.dart';
 import 'database.dart';
 
 /// A [Document] change event.
+///
+/// {@category Database}
 @immutable
 class DocumentChange {
   /// Creates a [Document] change event.

packages/cbl/lib/src/document/array.dart

@@ -14,6 +14,8 @@ import 'dictionary.dart';
 import 'fragment.dart';
 
 /// Defines a set of methods for readonly accessing array data.
+///
+/// {@category Document}
 abstract class ArrayInterface implements ArrayFragment {
   /// The number of elements in this array.
   int get length;
@@ -98,6 +100,8 @@ abstract class ArrayInterface implements ArrayFragment {
 }
 
 /// Provides readonly access to array data.
+///
+/// {@category Document}
 abstract class Array implements ArrayInterface, Iterable<Object?> {
   /// Returns a mutable copy of this array.
   MutableArray toMutable();
@@ -107,6 +111,8 @@ abstract class Array implements ArrayInterface, Iterable<Object?> {
 }
 
 /// Defines a set of methods for getting and setting array data.
+///
+/// {@category Document}
 abstract class MutableArrayInterface
     implements ArrayInterface, MutableArrayFragment {
   // === Set ===================================================================
@@ -203,7 +209,7 @@ abstract class MutableArrayInterface
 
   // === Insert ================================================================
 
-  /// Inserst a [value] [at] the given index.
+  /// Inserts a [value] [at] the given index.
   ///
   /// {@macro cbl.MutableArray.allowedValueTypes}
   ///
@@ -286,6 +292,8 @@ abstract class MutableArrayInterface
 }
 
 /// Provides access to array data.
+///
+/// {@category Document}
 abstract class MutableArray implements Array, MutableArrayInterface {
   /// Creates a [MutableArray], optionally initialized with [data].
   ///

packages/cbl/lib/src/document/blob.dart

@@ -29,6 +29,9 @@ const blobContentTypeProperty = 'content_type';
 /// Blob’s metadata (type, [length] and a [digest] of the data) in a small
 /// object. The data itself is stored externally to the document, keyed by the
 /// digest.
+///
+/// {@category Document}
+/// {@category Document}
 @immutable
 abstract class Blob {
   /// Creates a [Blob] with the given in-memory data.

packages/cbl/lib/src/document/dictionary.dart

@@ -14,6 +14,8 @@ import 'common.dart';
 import 'fragment.dart';
 
 /// Defines a set of methods for readonly accessing [Dictionary] data.
+///
+/// {@category Document}
 abstract class DictionaryInterface implements DictionaryFragment {
   /// The number of entries in this dictionary.
   int get length;
@@ -90,6 +92,8 @@ abstract class DictionaryInterface implements DictionaryFragment {
 }
 
 /// Provides readonly access to dictionary data.
+///
+/// {@category Document}
 abstract class Dictionary implements DictionaryInterface, Iterable<String> {
   /// Returns a mutable copy of this dictionary.
   MutableDictionary toMutable();
@@ -99,6 +103,8 @@ abstract class Dictionary implements DictionaryInterface, Iterable<String> {
 }
 
 /// Defines a set of methods for getting and setting dictionary data.
+///
+/// {@category Document}
 abstract class MutableDictionaryInterface
     implements DictionaryInterface, MutableDictionaryFragment {
   /// Sets a [value] for the given [key].
@@ -156,6 +162,8 @@ abstract class MutableDictionaryInterface
 }
 
 /// Provides access to dictionary data.
+///
+/// {@category Document}
 abstract class MutableDictionary
     implements Dictionary, MutableDictionaryInterface {
   /// Creates a [MutableDictionary], optionally initialized with [data].

packages/cbl/lib/src/document/document.dart

@@ -17,6 +17,8 @@ import 'fragment.dart';
 /// A Couchbase Lite document.
 ///
 /// The [Document] is immutable.
+///
+/// {@category Document}
 abstract class Document implements DictionaryInterface, Iterable<String> {
   /// The document’s id.
   String get id;
@@ -41,6 +43,8 @@ abstract class Document implements DictionaryInterface, Iterable<String> {
 }
 
 /// A mutable version of [Document].
+///
+/// {@category Document}
 abstract class MutableDocument implements Document, MutableDictionaryInterface {
   /// Creates a new [MutableDocument] with a random UUID, optionally
   /// initialized with [data].

packages/cbl/lib/src/document/fragment.dart

@@ -7,6 +7,8 @@ import 'dictionary.dart';
 import 'document.dart';
 
 /// Readonly access to the data value wrapped by a [Fragment] object.
+///
+/// {@category Document}
 abstract class FragmentInterface {
   /// The value of this fragment as a value of type [T].
   T? valueAs<T extends Object>();
@@ -46,6 +48,8 @@ abstract class FragmentInterface {
 }
 
 /// Read and write access to the data value wrapped by a [Fragment] object.
+///
+/// {@category Document}
 abstract class MutableFragmentInterface implements FragmentInterface {
   /// Sets the value of this fragment.
   ///
@@ -63,24 +67,32 @@ abstract class MutableFragmentInterface implements FragmentInterface {
 }
 
 /// Provides subscript access to [Fragment] objects by index.
+///
+/// {@category Document}
 abstract class ArrayFragment {
   /// Returns a [Fragment] for the value at the given [index].
   Fragment operator [](int index);
 }
 
 /// Provides subscript access to [MutableFragment] objects by index.
+///
+/// {@category Document}
 abstract class MutableArrayFragment {
   /// Returns a [MutableFragment] for the value at the given [index].
   MutableFragment operator [](int index);
 }
 
 /// Provides subscript access to [Fragment] objects by key.
+///
+/// {@category Document}
 abstract class DictionaryFragment {
   /// Returns a [Fragment] for the value at the given [key].
   Fragment operator [](String key);
 }
 
 /// Provides subscript access to [MutableFragment] objects by key.
+///
+/// {@category Document}
 abstract class MutableDictionaryFragment {
   /// Returns a [MutableFragment] for the value at the given [key].
   MutableFragment operator [](String key);
@@ -90,6 +102,8 @@ abstract class MutableDictionaryFragment {
 ///
 /// [Fragment] also provides subscript access by either key or index to the
 /// nested values which are wrapped by [Fragment] objects.
+///
+/// {@category Document}
 abstract class Fragment
     implements FragmentInterface, ArrayFragment, DictionaryFragment {
   Fragment operator [](Object indexOrKey);
@@ -99,6 +113,8 @@ abstract class Fragment
 ///
 /// [MutableFragment] also provides subscript access by either key or index to
 /// the nested values which are wrapped by [MutableFragment] objects.
+///
+/// {@category Document}
 abstract class MutableFragment
     implements
         Fragment,
@@ -112,6 +128,8 @@ abstract class MutableFragment
 ///
 /// [DocumentFragment] also provides subscript access by either key to
 /// the data values of the document which are wrapped by Fragment objects.
+///
+/// {@category Document}
 abstract class DocumentFragment implements DictionaryFragment {
   /// Whether the document exists in the database or not.
   bool get exists;

packages/cbl/lib/src/log/console_logger.dart

@@ -2,6 +2,8 @@ import '../support/ffi.dart';
 import 'logger.dart';
 
 /// Logger for writing log messages to the system console.
+///
+/// {@category Logging}
 abstract class ConsoleLogger {
   ConsoleLogger._();
 

packages/cbl/lib/src/log/file_logger.dart

@@ -8,6 +8,8 @@ import '../support/ffi.dart';
 import 'logger.dart';
 
 /// The configuration for log files.
+///
+/// {@category Logging}
 class LogFileConfiguration {
   /// Creates the configuration for log files.
   LogFileConfiguration({
@@ -106,6 +108,8 @@ class LogFileConfiguration {
 /// appropriately before setting it in the logger. The logger makes a copy of
 /// the instance you provide and uses that copy. Once configured, the logger
 /// object ignores any changes you make to the configuration.
+///
+/// {@category Logging}
 abstract class FileLogger {
   FileLogger._();
 

packages/cbl/lib/src/log/log.dart

@@ -3,6 +3,8 @@ import 'file_logger.dart';
 import 'logger.dart';
 
 /// Configuration of the [ConsoleLogger], [FileLogger] and a custom [Logger].
+///
+/// {@category Logging}
 abstract class Log {
   Log._();