Add docs and changelog entries

drift/CHANGELOG.md

@@ -1,6 +1,8 @@
 ## 2.12.0-dev
 
 - Add support for table-valued functions in the Dart query builder.
+- Add the `@TableIndex` annotation for table classes to add an index to the
+  table.
 - Support `json_each` and `json_tree`.
 
 ## 2.11.1

drift/lib/src/dsl/table.dart

@@ -238,9 +238,24 @@ abstract class View extends HasResultSet {
   Query as();
 }
 
+/// Annotations for Dart table classes to define a [SQL index](https://sqlite.org/lang_createindex.html)
+/// to add to the table.
+///
+/// ```dart
+/// @TableIndex(name: 'item_title', columns: {#title})
+/// class TodoItems extends Table {
+///   IntColumn get id => integer().autoIncrement()();
+///   TextColumn get title => text()();
+///   TextColumn get content => text().nullable()();
+/// }
+/// ```
 @Target({TargetKind.classType})
 final class TableIndex {
   /// The name of the index in SQL.
+  ///
+  /// Please note that the name of every table, view, index and other elements
+  /// in a database must be unique. For this reason, the names of indices are
+  /// commonly prefixed with the name of the table they're referencing.
   final String name;
 
   /// Whether this index is `UNIQUE`, meaning that the database will forbid
@@ -248,8 +263,18 @@ final class TableIndex {
   /// indexed columns.
   final bool unique;
 
+  /// The columns of the table that should be part of the index.
+  ///
+  /// Columns are referenced with a [Symbol] of their getter name used in the
+  /// column definition. For instance, a table declaring a column as
+  /// `IntColumn get nextUpdateSnapshot => ...()` could reference this column
+  /// using `#nextUpdateSnapshot`.
   final Set<Symbol> columns;
 
+  /// An annotation for Dart-defined drift tables telling drift to add an SQL
+  /// index to the table.
+  ///
+  /// See the class documentation at [TableIndex] for an example.
   const TableIndex({
     required this.name,
     required this.columns,

drift/pubspec.yaml

@@ -1,6 +1,6 @@
 name: drift
 description: Drift is a reactive library to store relational data in Dart and Flutter applications.
-version: 2.11.1
+version: 2.12.0-dev
 repository: https://github.com/simolus3/drift
 homepage: https://drift.simonbinder.eu/
 issue_tracker: https://github.com/simolus3/drift/issues

drift_dev/pubspec.yaml

@@ -1,6 +1,6 @@
 name: drift_dev
 description: Dev-dependency for users of drift. Contains the generator and development tools.
-version: 2.11.2
+version: 2.12.0-dev
 repository: https://github.com/simolus3/drift
 homepage: https://drift.simonbinder.eu/
 issue_tracker: https://github.com/simolus3/drift/issues
@@ -30,7 +30,7 @@ dependencies:
   io: ^1.0.3
 
   # Drift-specific analysis and apis
-  drift: '>=2.11.0 <2.12.0'
+  drift: '>=2.12.0 <2.13.0'
   sqlite3: '>=0.1.6 <3.0.0'
   sqlparser: '^0.31.0'