diff --git a/docs/pages/docs/Using SQL/drift_files.md b/docs/pages/docs/Using SQL/drift_files.md index 187d7300..e38a3bc2 100644 --- a/docs/pages/docs/Using SQL/drift_files.md +++ b/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 diff --git a/drift/test/generated/custom_tables.g.dart b/drift/test/generated/custom_tables.g.dart index d0e1c9f3..46498de7 100644 --- a/drift/test/generated/custom_tables.g.dart +++ b/drift/test/generated/custom_tables.g.dart @@ -623,6 +623,8 @@ class ConfigTable extends Table with TableInfo { class Config extends DataClass implements Insertable { final String configKey; + + /// The current value associated with the [configKey] final DriftAny? configValue; final SyncType? syncState; final SyncType? syncStateImplicit; diff --git a/drift/test/generated/tables.drift b/drift/test/generated/tables.drift index ded60910..36e7dc1b 100644 --- a/drift/test/generated/tables.drift +++ b/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) diff --git a/drift_dev/CHANGELOG.md b/drift_dev/CHANGELOG.md index a08c66c8..64758041 100644 --- a/drift_dev/CHANGELOG.md +++ b/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)). diff --git a/drift_dev/lib/src/analysis/resolver/drift/table.dart b/drift_dev/lib/src/analysis/resolver/drift/table.dart index cc8ae35e..8c41816e 100644 --- a/drift_dev/lib/src/analysis/resolver/drift/table.dart +++ b/drift_dev/lib/src/analysis/resolver/drift/table.dart @@ -162,6 +162,7 @@ class DriftTableResolver extends DriftElementResolver { 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 { return driftTable; } } + +extension on ColumnDefinition { + String? get documentationComment { + var lastBefore = first?.previous; + + final tokens = []; + + while (lastBefore is CommentToken) { + tokens.add(lastBefore); + lastBefore = lastBefore.previous; + } + + if (tokens.isEmpty) return null; + + return tokens.map((t) => '///${t.content}').join('\n'); + } +} diff --git a/drift_dev/pubspec.yaml b/drift_dev/pubspec.yaml index 814cb004..f6596d53 100644 --- a/drift_dev/pubspec.yaml +++ b/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 diff --git a/drift_dev/test/analysis/resolver/drift/table_test.dart b/drift_dev/test/analysis/resolver/drift/table_test.dart index 25bc7b26..ec5e89ce 100644 --- a/drift_dev/test/analysis/resolver/drift/table_test.dart +++ b/drift_dev/test/analysis/resolver/drift/table_test.dart @@ -220,4 +220,26 @@ CREATE TABLE waybills ( isA().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().having((e) => e.documentationComment, + 'documentationComment', '/// The name of this currency'), + ); + }); } diff --git a/sqlparser/CHANGELOG.md b/sqlparser/CHANGELOG.md index f7b9a431..bd843ca6 100644 --- a/sqlparser/CHANGELOG.md +++ b/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. diff --git a/sqlparser/lib/src/reader/tokenizer/scanner.dart b/sqlparser/lib/src/reader/tokenizer/scanner.dart index 72b39114..4c45b32c 100644 --- a/sqlparser/lib/src/reader/tokenizer/scanner.dart +++ b/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) { diff --git a/sqlparser/lib/src/reader/tokenizer/token.dart b/sqlparser/lib/src/reader/tokenizer/token.dart index 3315edc4..b7a1f5ef 100644 --- a/sqlparser/lib/src/reader/tokenizer/token.dart +++ b/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 diff --git a/sqlparser/pubspec.yaml b/sqlparser/pubspec.yaml index 65b6576f..70b2ba31 100644 --- a/sqlparser/pubspec.yaml +++ b/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/