Add dartdoc comments

drift/lib/src/web/wasm_setup/shared.dart

@@ -79,14 +79,22 @@ Future<bool> checkIndexedDbSupport() async {
   return true;
 }
 
+/// Constructs the path used by drift to store a database in the origin-private
+/// section of the agent's file system.
 String pathForOpfs(String databaseName) {
   return 'drift_db/$databaseName';
 }
 
+/// Manages drift servers.
+///
+/// When using a shared worker, multiple clients may want to use different drift
+/// databases. This server keeps track of drift servers by their database names
+/// to allow that.
 class DriftServerController {
   /// Running drift servers by the name of the database they're serving.
   final Map<String, DriftServer> _servers = {};
 
+  /// Serves a drift connection as requested by the [message].
   void serve(ServeDriftDatabase message) {
     final server = _servers.putIfAbsent(message.databaseName, () {
       return DriftServer(LazyDatabase(() async {

drift/lib/src/web/wasm_setup/shared_worker.dart

@@ -3,7 +3,6 @@ import 'dart:async';
 import 'dart:html';
 
 import 'package:drift/wasm.dart';
-import 'package:js/js.dart';
 import 'package:js/js_util.dart';
 
 import '../wasm_setup.dart';

drift/lib/wasm.dart

@@ -71,6 +71,7 @@ class WasmDatabase extends DelegatedDatabase {
         _WasmDelegate(sqlite3, null, setup, null), logStatements);
   }
 
+  /// For an in-depth
   static Future<WasmDatabaseResult> open({
     required String databaseName,
     required Uri sqlite3Uri,
@@ -83,6 +84,15 @@ class WasmDatabase extends DelegatedDatabase {
     ).open();
   }
 
+  /// The entrypoint for a web worker suitable for use with [open].
+  ///
+  /// Generally, you can grab a pre-compiled worker file from a
+  /// [drift release](https://github.com/simolus3/drift/releases) and don't need
+  /// to call this method in your app.
+  ///
+  /// If you prefer to compile the worker yourself, write a simple Dart program
+  /// that calls this method in its `main()` function and compile that with
+  /// `dart2js`.
   static void workerMainForOpen() {
     final self = WorkerGlobalScope.instance;
 
@@ -216,12 +226,14 @@ enum WasmStorageImplementation {
   /// [cross-origin isolation]: https://developer.mozilla.org/en-US/docs/Web/API/crossOriginIsolated
   opfsLocks,
 
+  /// Emulates a file system over `IndexedDB` in a shared worker.
   sharedIndexedDb,
 
   /// Uses the asynchronous IndexedDB API outside of any worker to persist data.
   ///
-  /// Unlike [opfsShared] or [opfsLocks], this storage implementation can't
-  /// prevent two tabs from accessing the same data.
+  /// Unlike [opfsShared], [opfsLocks] or [sharedIndexedDb], this storage
+  /// implementation can't prevent data races if your app is opened in multiple
+  /// tabs at the same time, which is why it's declared as as unsafe.
   unsafeIndexedDb,
 
   /// A fallback storage implementation that doesn't store anything.
@@ -232,22 +244,67 @@ enum WasmStorageImplementation {
   inMemory,
 }
 
+/// An enumeration of features not supported by the current browsers.
+///
+/// While this information may not be useful to end users, it can be used to
+/// understand why drift has chosen a particular storage implementation in
+/// [WasmDatabaseResult].
 enum MissingBrowserFeature {
+  /// The browser is missing support for [shared workers].
+  ///
+  /// [shared workers]: https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker
   sharedWorkers,
+
+  /// The browser is missing support for [web workers] in general.
+  ///
+  /// [web workers]: https://developer.mozilla.org/en-US/docs/Web/API/Worker
   dedicatedWorkers,
+
+  /// The browser doesn't allow shared workers to spawn dedicated workers in
+  /// their context.
+  ///
+  /// While the specification for web workers explicitly allows this, this
+  /// feature is only implemented by Firefox at the time of writing.
   dedicatedWorkersInSharedWorkers,
-  nestedDedicatedWorkers,
+
+  /// The browser does not support a synchronous version of the [File System API]
+  ///
+  /// [File System API]: https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API
   fileSystemAccess,
+
+  /// The browser does not support IndexedDB.
   indexedDb,
+
+  /// The browser does not support shared array buffers and `Atomics.wait`.
+  ///
+  /// To enable this feature in most browsers, you need to serve your app with
+  /// two [special headers](https://web.dev/coop-coep/).
   sharedArrayBuffers,
-  notCrossOriginIsolated,
 }
 
+/// The result of opening a WASM database.
 class WasmDatabaseResult {
+  /// The drift database connection to pass to the [GeneratedDatabase.new]
+  /// constructor of your database class to use the opened database.
   final DatabaseConnection resolvedExecutor;
+
+  /// For your reference, the chosen storage implementation.
+  ///
+  /// Depending on the features available in the browser your app runs on, drift
+  /// will use the most reliable implementation in [WasmStorageImplementation].
+  ///
+  /// If the implementation can't store data reliably ([WasmStorageImplementation.unsafeIndexedDb])
+  /// or not at all ([WasmStorageImplementation.inMemory]), you may want to show
+  /// a warning to the user if persistence is important in your app.
   final WasmStorageImplementation chosenImplementation;
+
+  /// An enumeration of missing browser features probed by drift.
+  ///
+  /// The lack of support of features listed here contributed to the
+  /// [chosenImplementation] for the virtual file system used to store databases.
   final Set<MissingBrowserFeature> missingFeatures;
 
-  WasmDatabaseResult(
+  /// Default constructor from the invidiual fields.
+  const WasmDatabaseResult(
       this.resolvedExecutor, this.chosenImplementation, this.missingFeatures);
 }