Support doc comments for columns in drift files

docs/pages/docs/Using SQL/drift_files.md

@@ -425,6 +425,24 @@ Internally, drift will then generate query code to map the row to an instance of
 For a more complete overview of using custom row classes for queries, see
 [the section for queries]({{ '../Advanced Features/custom_row_classes.md#queries' | pageUrl }}).
 
+### Dart documentation comments
+
+Comments added before columns in a drift file are added as Dart documentation comments
+in the generated row class:
+
+```sql
+CREATE TABLE friends (
+  -- The user original sending the friendship request
+  user_a INTEGER NOT NULL REFERENCES users(id),
+  -- The user accepting the friendship request from [userA].
+  user_b INTEGER NOT NULL REFERENCES users(id),
+  PRIMARY KEY (user_a, user_b)
+);
+```
+
+The generated `userA` and `userB` field in the `Friend` class generated by drift will
+have these comments as documentation comments.
+
 ## Result class names
 
 For most queries, drift generates a new class to hold the result. This class is named after the query

drift/test/generated/custom_tables.g.dart

@@ -623,6 +623,8 @@ class ConfigTable extends Table with TableInfo<ConfigTable, Config> {
 
 class Config extends DataClass implements Insertable<Config> {
   final String configKey;
+
+  /// The current value associated with the [configKey]
   final DriftAny? configValue;
   final SyncType? syncState;
   final SyncType? syncStateImplicit;

drift/test/generated/tables.drift

@@ -20,6 +20,7 @@ CREATE TABLE with_constraints (
 
 create table config (
     config_key TEXT not null primary key,
+    -- The current value associated with the [configKey]
     config_value ANY,
     sync_state INTEGER MAPPED BY `const SyncTypeConverter()`,
     sync_state_implicit ENUM(SyncType)

drift_dev/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.9.0-dev
+
+- Add documentation comments for comments on columns in drift files.
+
 ## 2.8.0
 
 - Support named constructors for existing row types in drift files ([#2399](https://github.com/simolus3/drift/issues/2399)).

drift_dev/lib/src/analysis/resolver/drift/table.dart

@@ -162,6 +162,7 @@ class DriftTableResolver extends DriftElementResolver<DiscoveredDriftTable> {
         constraints: constraints,
         typeConverter: converter,
         defaultArgument: defaultArgument,
+        documentationComment: column.definition?.documentationComment,
         customConstraints: customConstraintsForDrift.toString(),
         declaration: DriftDeclaration.driftFile(
           column.definition?.nameToken ?? stmt,
@@ -341,3 +342,20 @@ class DriftTableResolver extends DriftElementResolver<DiscoveredDriftTable> {
     return driftTable;
   }
 }
+
+extension on ColumnDefinition {
+  String? get documentationComment {
+    var lastBefore = first?.previous;
+
+    final tokens = <CommentToken>[];
+
+    while (lastBefore is CommentToken) {
+      tokens.add(lastBefore);
+      lastBefore = lastBefore.previous;
+    }
+
+    if (tokens.isEmpty) return null;
+
+    return tokens.map((t) => '///${t.content}').join('\n');
+  }
+}

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.8.0
+version: 2.9.0-dev
 repository: https://github.com/simolus3/drift
 homepage: https://drift.simonbinder.eu/
 issue_tracker: https://github.com/simolus3/drift/issues

drift_dev/test/analysis/resolver/drift/table_test.dart

@@ -220,4 +220,26 @@ CREATE TABLE waybills (
         isA<DriftColumn>().having(
             (e) => e.overriddenJsonName, 'overriddenJsonName', 'parentDoc'));
   });
+
+  test('recognizes documentation comments', () async {
+    final state = TestBackend.inTest({
+      'a|lib/a.drift': '''
+CREATE TABLE IF NOT EXISTS currencies (
+  -- The name of this currency
+  name TEXT NOT NULL PRIMARY KEY,
+  symbol TEXT NOT NULL
+);
+''',
+    });
+
+    final file = await state.analyze('package:a/a.drift');
+    state.expectNoErrors();
+
+    final table = file.analyzedElements.single as DriftTable;
+    expect(
+      table.columnBySqlName['name'],
+      isA<DriftColumn>().having((e) => e.documentationComment,
+          'documentationComment', '/// The name of this currency'),
+    );
+  });
 }

sqlparser/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.30.0-dev
+
+- Add `previous` and `next` fields for tokens
+
 ## 0.29.0
 
 - Parser support for constructor names in `WITH` drift syntax.

sqlparser/lib/src/reader/tokenizer/scanner.dart

@@ -42,8 +42,14 @@ class Scanner {
     final endSpan = _file.span(source.length);
     tokens.add(Token(TokenType.eof, endSpan));
 
+    Token? previous;
     for (var i = 0; i < tokens.length; i++) {
-      tokens[i].index = i;
+      final current = tokens[i];
+      current.index = i;
+      current.previous = previous;
+      previous?.next = current;
+
+      previous = current;
     }
 
     if (errors.isNotEmpty) {

sqlparser/lib/src/reader/tokenizer/token.dart

@@ -453,6 +453,8 @@ class Token implements SyntacticEntity {
   /// The index of this [Token] in the list of tokens scanned.
   late int index;
 
+  Token? previous, next;
+
   Token(this.type, this.span);
 
   @override

sqlparser/pubspec.yaml

@@ -1,6 +1,6 @@
 name: sqlparser
 description: Parses sqlite statements and performs static analysis on them
-version: 0.29.0
+version: 0.30.0-dev
 homepage: https://github.com/simolus3/drift/tree/develop/sqlparser
 repository: https://github.com/simolus3/drift
 #homepage: https://drift.simonbinder.eu/