Add toptics to dartdoc documentation

Author: simolus3

sqlite3/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## 2.7.3-dev
 
 - Web: Support `localtime` datetime modifier in SQLite.
+- Introduce topics to dartdoc documentation.
 
 ## 2.7.2
 

sqlite3/dartdoc_options.yaml

@@ -0,0 +1,11 @@
+dartdoc:
+  categories:
+    "common":
+      markdown: doc/common.md
+      name: Cross-platform definitions
+    "native":
+      markdown: doc/native.md
+      name: Native only
+    "wasm":
+      markdown: doc/wasm.md
+      name: Web only

sqlite3/doc/common.md

@@ -0,0 +1,54 @@
+Definitions and common interfaces that are implemented by both the native
+and the web-specific bindings to SQLite.
+
+Restricting your usage of the sqlite3 package to `package:sqlite3/common.dart`
+means that your code can run on all platforms.
+However, this doesn't give you access to the actual implementations that are part
+of the native and web implementations.
+You can write most of your database code with the common definitions and then use
+conditional imports to make an implementation available. For this, create three files:
+
+1. `database_stub.dart`.
+2. `database_native.dart`.
+3. `datbaase_web.dart`.
+
+The content of these files depends on your needs, but could look like this:
+
+```dart
+// database_stub.dart
+import 'package:sqlite3/common.dart';
+
+Future<CommonDatabase> openDatabase() async {
+  throw UnsupportedError('Unknown platform');
+}
+```
+
+```dart
+// database_native.dart
+import 'package:sqlite3/sqlite3.dart';
+
+Future<CommonDatabase> openDatabase() async {
+  final path = await pickDatabasePath(); // e.g. with package:path_provider
+  return sqlite3.open(path);
+}
+```
+
+```dart
+// database_web.dart
+import 'package:sqlite3/wasm.dart';
+
+Future<CommonDatabase> openDatabase() async {
+  final sqlite = await WasmSqlite3.loadFromUrl(Uri.parse('sqlite3.wasm'));
+  final fs = await IndexedDbFileSystem.open(dbName: 'app.db');
+  sqlite.registerVirtualFileSystem(fs, makeDefault: true);
+  return sqlite.open('/app.db');
+}
+```
+
+With those files, you can use a conditional imports to support both web and native platforms:
+
+```dart
+import 'database_stub.dart'
+    if (dart.library.io) 'database_native.dart'
+    if (dart.library.js_interop) 'database_web.dart';
+```

sqlite3/doc/native.md

@@ -0,0 +1 @@
+Libraries related to accessing SQLite functions via `dart:ffi` on native platforms.

sqlite3/doc/wasm.md

@@ -0,0 +1 @@
+APIs for using SQLite in web contexts, accessing SQLite through a WebAssembly module.

sqlite3/lib/common.dart

@@ -1,5 +1,9 @@
 /// Exports common interfaces that are implemented by both the `dart:ffi` and
 /// the `dart:js` WASM version of this library.
+///
+/// {@category common}
+/// {@canonicalFor database.CommonDatabase}
+/// {@canonicalFor statement.CommonPreparedStatement}
 library;
 
 export 'src/constants.dart';

sqlite3/lib/open.dart

@@ -1,5 +1,7 @@
 /// Utils to open a [DynamicLibrary] on platforms that aren't supported by
 /// default.
+///
+/// {@category native}
 library;
 
 import 'dart:ffi';

sqlite3/lib/sqlite3.dart

@@ -1,4 +1,6 @@
 /// Dart bindings to `sqlite3`.
+///
+/// {@category native}
 library;
 
 // Hide common base classes that have more specific ffi-APIs.

sqlite3/lib/src/constants.dart

@@ -10,6 +10,7 @@
 ///
 /// See also: SQLITE_IOERR_READ | extended result codes,
 /// sqlite3_vtab_on_conflictstatic const int ) SQLITE_ROLLBACK | result codes.
+/// {@category common}
 final class SqlError {
   /// Successful result
   static const int SQLITE_OK = 0;
@@ -112,6 +113,7 @@ final class SqlError {
 /// Note that the primary result code is always a part of the extended result code. Given a full 32-bit extended result code, the application can always find the corresponding primary result code merely by extracting the least significant 8 bits of the extended result code.
 ///
 /// All extended result codes are also error codes. Hence the terms "extended result code" and "extended error code" are interchangeable.
+/// {@category common}
 final class SqlExtendedError {
   /// The sqlite3_load_extension() interface loads an extension into a single database connection.
   ///
@@ -374,6 +376,7 @@ final class SqlExtendedError {
 /// These bit values are intended for use in the
 /// 3rd parameter to the [sqlite3_open_v2static const int )] interface and
 /// in the 4th parameter to the `xopen` method.
+/// {@category common}
 final class SqlFlag {
   /// Ok for sqlite3_open_v2static const int )
   static const int SQLITE_OPEN_READONLY = 0x00000001;
@@ -436,7 +439,9 @@ final class SqlFlag {
   static const int SQLITE_OPEN_WAL = 0x00080000;
 }
 
-// Prepare flags, https://www.sqlite.org/c3ref/c_prepare_normalize.html
+/// Prepare flags, https://www.sqlite.org/c3ref/c_prepare_normalize.html
+///
+/// {@category common}
 final class SqlPrepareFlag {
   ///The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner that the prepared statement will be retained for a long time and probably reused many times.
   /// Without this flag, sqlite3_prepare_v3static const int ) and sqlite3_prepare16_v3static const int ) assume that the prepared statement will be used just once or at most a few times and then destroyed using sqlite3_finalizestatic const int ) relatively soon.
@@ -453,6 +458,8 @@ final class SqlPrepareFlag {
 }
 
 /// Datatypes, https://sqlite.org/c3ref/c_blob.html
+///
+/// {@category common}
 final class SqlType {
   static const int SQLITE_INTEGER = 1;
   static const int SQLITE_FLOAT = 2;
@@ -463,6 +470,8 @@ final class SqlType {
 
 /// Text Encodings, https://www.sqlite.org/c3ref/c_any.html
 /// These constant define integer codes that represent the various text encodings supported by SQLite.
+///
+/// {@category common}
 final class SqlTextEncoding {
   ///IMP: R-37514-35566
   static const int SQLITE_UTF8 = 1;
@@ -484,6 +493,8 @@ final class SqlTextEncoding {
 }
 
 /// File lock levels, https://www.sqlite.org/c3ref/c_lock_exclusive.html
+///
+/// {@category common}
 final class SqlFileLockingLevels {
   static const SQLITE_LOCK_NONE = 0;
   static const SQLITE_LOCK_SHARED = 1;
@@ -493,6 +504,8 @@ final class SqlFileLockingLevels {
 }
 
 /// Special destructors, https://www.sqlite.org/c3ref/c_static.html
+///
+/// {@category common}
 final class SqlSpecialDestructor {
   /// it means that the content pointer is constant and will never change, It does not need to be destroyed
   static const SQLITE_STATIC = 0;
@@ -503,6 +516,8 @@ final class SqlSpecialDestructor {
 }
 
 /// Function flags, https://www.sqlite.org/c3ref/c_deterministic.html
+///
+/// {@category common}
 final class SqlFunctionFlag {
   /// The SQLITE_DETERMINISTIC flag means that the new function always gives the same output when the input parameters are the same
   static const SQLITE_DETERMINISTIC = 0x000000800;

sqlite3/lib/src/database.dart

@@ -4,6 +4,8 @@ import 'statement.dart';
 import 'constants.dart';
 
 /// An opened sqlite3 database.
+///
+/// {@category common}
 abstract class CommonDatabase {
   /// Configuration for the database connection.
   ///
@@ -247,6 +249,8 @@ abstract class CommonDatabase {
 
 /// The kind of an [SqliteUpdate] received through a [CommonDatabase.updates]
 /// stream.
+///
+/// {@category common}
 enum SqliteUpdateKind {
   // Note: Changing the order of these fields is a breaking change, as they're
   // used in the sqlite3_web protocol.
@@ -262,6 +266,8 @@ enum SqliteUpdateKind {
 }
 
 /// A data change notification from sqlite.
+///
+/// {@category common}
 final class SqliteUpdate {
   /// The kind of write being reported.
   final SqliteUpdateKind kind;
@@ -295,6 +301,8 @@ final class SqliteUpdate {
 ///
 /// More information: https://www.sqlite.org/c3ref/db_config.html
 /// Available options are documented in https://www.sqlite.org/c3ref/c_dbconfig_defensive.html
+///
+/// {@category common}
 abstract base class DatabaseConfig {
   /// Update configuration that accepts an int value.
   /// Would throw when the internal C call returns a non-zero value.

sqlite3/lib/src/exception.dart

@@ -4,6 +4,8 @@ import 'dart:typed_data';
 ///
 /// This is the only exception thrown by `package:sqlite3`. Additionally, errors
 /// might be thrown on api misuse.
+///
+/// {@category common}
 final class SqliteException implements Exception {
   /// An error message indicating what went wrong.
   final String message;

sqlite3/lib/src/ffi/api.dart

@@ -9,11 +9,15 @@ import 'implementation.dart';
 Sqlite3? _sqlite3;
 
 /// Provides access to `sqlite3` functions, such as opening new databases.
+///
+/// {@category native}
 Sqlite3 get sqlite3 {
   return _sqlite3 ??= FfiSqlite3(open.openSqlite());
 }
 
 /// Provides access to `sqlite3` functions, such as opening new databases.
+///
+/// {@category native}
 abstract interface class Sqlite3 implements CommonSqlite3 {
   @override
   Database open(
@@ -60,6 +64,8 @@ abstract interface class Sqlite3 implements CommonSqlite3 {
 ///  - this C file: https://github.com/simolus3/sqlite3.dart/blob/main/sqlite3/test/ffi/test_extension.c
 ///  - this Dart test loading it: https://github.com/simolus3/sqlite3.dart/blob/a9a379494c6b8d58a3c31cf04fe16e83b49130f1/sqlite3/test/ffi/sqlite3_test.dart#L35
 ///  - Or, alternatively, this Flutter example: https://github.com/simolus3/sqlite3.dart/tree/main/sqlite3/example/custom_extension
+///
+/// {@category native}
 abstract interface class SqliteExtension {
   /// A sqlite extension having the given [extensionEntrypoint] as a function
   /// pointer.
@@ -95,6 +101,8 @@ abstract interface class SqliteExtension {
 ///
 /// See [CommonDatabase] for the methods that are available on both the FFI and
 /// the WebAssembly implementation.
+///
+/// {@category native}
 abstract class Database extends CommonDatabase {
   /// The native database connection handle from sqlite.
   ///
@@ -132,6 +140,8 @@ abstract class Database extends CommonDatabase {
 }
 
 /// A prepared statement.
+///
+/// {@category native}
 abstract class PreparedStatement implements CommonPreparedStatement {
   /// The underlying `sqlite3_stmt` pointer.
   ///

sqlite3/lib/src/ffi/load_library.dart

@@ -5,8 +5,14 @@ import 'dart:math';
 import 'package:meta/meta.dart';
 
 /// Signature responsible for loading the dynamic sqlite3 library to use.
+///
+/// {@category native}
 typedef OpenLibrary = DynamicLibrary Function();
 
+/// An operating system supported by `package:sqlite3` when opening SQLite
+/// libraries.
+///
+/// {@category native}
 enum OperatingSystem {
   android,
   linux,
@@ -19,6 +25,8 @@ enum OperatingSystem {
 /// The instance managing different approaches to load the [DynamicLibrary] for
 /// sqlite when needed. See the documentation for [OpenDynamicLibrary] to learn
 /// how the default opening behavior can be overridden.
+///
+/// {@category native}
 final OpenDynamicLibrary open = OpenDynamicLibrary._();
 
 DynamicLibrary _defaultOpen() {
@@ -93,6 +101,8 @@ DynamicLibrary _defaultOpen() {
 /// The default behavior can be overridden for a specific OS by using
 /// [overrideFor]. To override the behavior on all platforms, use
 /// [overrideForAll].
+///
+/// {@category native}
 final class OpenDynamicLibrary {
   final Map<OperatingSystem, OpenLibrary> _overriddenPlatforms = {};
   OpenLibrary? _overriddenForAll;

sqlite3/lib/src/functions.dart

@@ -51,6 +51,8 @@ typedef ScalarFunction = Object? Function(List<Object?> arguments);
 ///  }
 ///}
 /// ```
+///
+/// {@category common}
 @immutable
 abstract class AggregateFunction<V> {
   /// Creates an initial context holding the initial value before [step] is
@@ -114,6 +116,8 @@ abstract class AggregateFunction<V> {
 ///  Object? value(AggregateContext<int> context) => context.value;
 ///}
 /// ```
+///
+/// {@category common}
 
 @immutable
 abstract class WindowFunction<V> implements AggregateFunction<V> {
@@ -128,6 +132,8 @@ abstract class WindowFunction<V> implements AggregateFunction<V> {
 }
 
 /// Application-defined context used to compute results in aggregate functions.
+///
+/// {@category common}
 final class AggregateContext<V> {
   /// The current value of this context.
   V value;
@@ -137,6 +143,8 @@ final class AggregateContext<V> {
 }
 
 /// Describes how many arguments an application-defined sql function can take.
+///
+/// {@category common}
 final class AllowedArgumentCount {
   final int allowedArgs;
 

sqlite3/lib/src/in_memory_vfs.dart

@@ -13,6 +13,8 @@ import 'utils.dart';
 /// This file system is commonly used on the web as a buffer in front of
 /// asynchronous storage APIs like IndexedDb. It can also serve as an example on
 /// how to write custom file systems to be used with sqlite3.
+///
+/// {@category common}
 final class InMemoryFileSystem extends BaseVirtualFileSystem {
   final Map<String, Uint8Buffer?> fileData = {};
 

sqlite3/lib/src/jsonb.dart

@@ -37,6 +37,7 @@ import 'package:typed_data/typed_buffers.dart';
 /// ```
 ///
 /// [JSONB]: https://sqlite.org/jsonb.html
+/// {@category common}
 const Codec<Object?, Uint8List> jsonb = _JsonbCodec();
 
 final class _JsonbCodec extends Codec<Object?, Uint8List> {

sqlite3/lib/src/result_set.dart

@@ -7,6 +7,8 @@ import 'package:meta/meta.dart';
 ///
 /// Result sets are either completely materialized ([ResultSet] with all rows
 /// being directly available), or executed row-by-row ([IteratingCursor]).
+///
+/// {@category common}
 sealed class Cursor {
   List<String> _columnNames;
 
@@ -51,11 +53,15 @@ sealed class Cursor {
 /// names might change in the first call to [moveNext]. So, these getters are
 /// only reliable after [moveNext] was called once (regardless of its return
 /// value).
+///
+/// {@category common}
 abstract class IteratingCursor extends Cursor implements Iterator<Row> {
   IteratingCursor(super._columnNames, super.tableNames);
 }
 
 /// Stores the full result of a select statement.
+///
+/// {@category common}
 final class ResultSet extends Cursor
     with
         ListMixin<Row>,
@@ -88,6 +94,8 @@ final class ResultSet extends Cursor
 /// value of a column by its name.
 /// The [columnAt] method may be used to obtain the value of a column by its
 /// index.
+///
+/// {@category common}
 final class Row
     with
         // ignore: prefer_mixin