Add documentation comments, fix analysis warnings

docs/lib/snippets/isolates.dart

@@ -37,7 +37,7 @@ DatabaseConnection _backgroundConnection() {
   // using a Flutter plugin like `path_provider` to determine the path, also see
   // the "Initialization on the main thread" section below!
   final database = NativeDatabase.memory();
-  return DatabaseConnection.fromExecutor(database);
+  return DatabaseConnection(database);
 }
 
 void main() async {
@@ -101,7 +101,7 @@ void _startBackground(_IsolateStartRequest request) {
   // background isolate. If we used DriftIsolate.spawn, a third isolate would be
   // started which is not what we want!
   final driftIsolate = DriftIsolate.inCurrent(
-    () => DatabaseConnection.fromExecutor(executor),
+    () => DatabaseConnection(executor),
   );
   // inform the starting isolate about this, so that it can call .connect()
   request.sendDriftIsolate.send(driftIsolate);

drift/lib/src/runtime/api/options.dart

@@ -1,8 +1,19 @@
 import '../types/mapping.dart';
 
+/// Database-specific options used by drift.
+///
+/// Instances of this class are primarily meant to be generated by `drift_dev`,
+/// which will override the database options based on compile-time options.
 class DriftDatabaseOptions {
+  /// Configuration for [SqlTypes] describing how to map Dart values from and to
+  /// SQL values.
   final SqlTypes types;
 
+  /// Creates database-specific database options.
+  ///
+  /// When [storeDateTimeAsText] is enabled (it defaults to `false` for
+  /// backwards-compatibility), drift's datetime columns will be stored as text.
+  /// By default, they will be stored as ints.
   DriftDatabaseOptions({
     bool storeDateTimeAsText = false,
   }) : types = SqlTypes(storeDateTimeAsText);

drift/lib/src/runtime/query_builder/query_builder.dart

@@ -12,8 +12,6 @@ import 'package:meta/meta.dart';
 
 // New files should not be part of this mega library, which we're trying to
 // split up.
-import '../api/options.dart';
-import '../types/mapping.dart';
 import 'expressions/case_when.dart';
 
 export 'on_table.dart';

drift/lib/src/runtime/query_builder/statements/select/custom_select.dart

@@ -72,8 +72,12 @@ class QueryRow {
   QueryRow(this.data, this._db);
 
   /// Reads an arbitrary value from the row and maps it to a fitting dart type.
+  ///
   /// The dart type [T] must be supported by the type system of the database
   /// used (mostly contains booleans, strings, numbers and dates).
+  ///
+  /// This method always reads non-nullable values. To read nullable columns,
+  /// use [readNullable].
   T read<T extends Object>(String key) {
     final result = readNullable<T>(key);
     if (result == null) {
@@ -85,6 +89,10 @@ class QueryRow {
     }
   }
 
+  /// Reads a nullable value from this row.
+  ///
+  /// Just like for the non-nullable [read], the type [T] must be supported by
+  /// drift (e.g. booleans, strings, numbers, dates, `Uint8List`s).
   T? readNullable<T extends Object>(String key) {
     final type = DriftSqlType.forType<T>();
     return _db.options.types.read(type, data[key]);

drift_dev/lib/src/services/schema/verifier_impl.dart

@@ -69,7 +69,7 @@ class VerifierImplementation implements SchemaVerifier {
 
     return InitializedSchema(dbForUse, () {
       final db = sqlite3.open(uri, uri: true);
-      return DatabaseConnection.fromExecutor(NativeDatabase.opened(db));
+      return DatabaseConnection(NativeDatabase.opened(db));
     });
   }
 

examples/app/lib/database/connection/native.dart

@@ -52,8 +52,8 @@ void _entrypointForDriftIsolate(_IsolateStartRequest request) {
 
   // We can use DriftIsolate.inCurrent because this function is the entrypoint
   // of a background isolate itself.
-  final driftServer = DriftIsolate.inCurrent(
-      () => DatabaseConnection.fromExecutor(databaseImpl));
+  final driftServer =
+      DriftIsolate.inCurrent(() => DatabaseConnection(databaseImpl));
 
   // Inform the main isolate about the server we just created.
   request.talkToMain.send(driftServer);

examples/app/lib/database/connection/web.dart

@@ -31,7 +31,7 @@ DatabaseConnection connect({bool isInWebWorker = false}) {
       );
 
       final databaseImpl = WasmDatabase(sqlite3: sqlite3, path: 'app.db');
-      return DatabaseConnection.fromExecutor(databaseImpl);
+      return DatabaseConnection(databaseImpl);
     }));
   }
 }

examples/app/test/database_test.dart

@@ -8,7 +8,7 @@ void main() {
   late AppDatabase database;
 
   setUp(() {
-    final inMemory = DatabaseConnection.fromExecutor(NativeDatabase.memory());
+    final inMemory = DatabaseConnection(NativeDatabase.memory());
     database = AppDatabase.forTesting(inMemory);
   });
 

examples/flutter_web_worker_example/web/worker.dart

@@ -11,7 +11,7 @@ void main() {
 
   final db = WebDatabase.withStorage(DriftWebStorage.indexedDb('worker',
       migrateFromLocalStorage: false, inWebWorker: true));
-  final server = DriftServer(DatabaseConnection.fromExecutor(db));
+  final server = DriftServer(DatabaseConnection(db));
 
   self.onConnect.listen((event) {
     final msg = event as MessageEvent;

examples/web_worker_example/web/worker.dart

@@ -10,7 +10,7 @@ void main() {
 
   final db = WebDatabase.withStorage(DriftWebStorage.indexedDb('worker',
       migrateFromLocalStorage: false, inWebWorker: true));
-  final server = DriftServer(DatabaseConnection.fromExecutor(db));
+  final server = DriftServer(DatabaseConnection(db));
 
   self.onConnect.listen((event) {
     final msg = event as MessageEvent;

extras/drift_postgres/test/drift_postgres_test.dart

@@ -10,7 +10,7 @@ class PgExecutor extends TestExecutor {
   DatabaseConnection createConnection() {
     final pgConnection = PostgreSQLConnection('localhost', 5432, 'postgres',
         username: 'postgres', password: 'postgres');
-    return DatabaseConnection.fromExecutor(PgDatabase(pgConnection));
+    return DatabaseConnection(PgDatabase(pgConnection));
   }
 
   @override

extras/integration_tests/drift_testcases/lib/database/database.dart

@@ -90,8 +90,7 @@ class Database extends _$Database {
 
   Database(DatabaseConnection e, {this.schemaVersion = 2}) : super.connect(e);
 
-  Database.executor(QueryExecutor db)
-      : this(DatabaseConnection.fromExecutor(db));
+  Database.executor(QueryExecutor db) : this(DatabaseConnection(db));
 
   /// It will be set in the onUpgrade callback. Null if no migration occurred
   int? schemaVersionChangedFrom;

extras/integration_tests/ffi_on_flutter/integration_test/drift_native.dart

@@ -22,8 +22,7 @@ class FfiExecutor extends TestExecutor {
 
   @override
   DatabaseConnection createConnection() {
-    return DatabaseConnection.fromExecutor(
-        NativeDatabase(File(join(dbPath, 'app_ffi.db'))));
+    return DatabaseConnection(NativeDatabase(File(join(dbPath, 'app_ffi.db'))));
   }
 
   @override
@@ -98,5 +97,5 @@ Future<void> main() async {
 }
 
 DatabaseConnection _openInBackground() {
-  return DatabaseConnection.fromExecutor(NativeDatabase.memory());
+  return DatabaseConnection(NativeDatabase.memory());
 }

extras/integration_tests/web/test/integration_test.dart

@@ -18,7 +18,7 @@ class WebExecutor extends TestExecutor {
 
   @override
   DatabaseConnection createConnection() {
-    return DatabaseConnection.fromExecutor(WebDatabase(name));
+    return DatabaseConnection(WebDatabase(name));
   }
 
   @override
@@ -34,7 +34,7 @@ class WebExecutorIndexedDb extends TestExecutor {
 
   @override
   DatabaseConnection createConnection() {
-    return DatabaseConnection.fromExecutor(
+    return DatabaseConnection(
       WebDatabase.withStorage(DriftWebStorage.indexedDb('foo')),
     );
   }
@@ -55,7 +55,7 @@ void main() {
   });
 
   test('can run multiple statements in one call', () async {
-    final db = Database(DatabaseConnection.fromExecutor(
+    final db = Database(DatabaseConnection(
         WebDatabase.withStorage(DriftWebStorage.volatile())));
     addTearDown(db.close);