feat: add support for documentation comments

extras/integration_tests/tests/lib/database/database.dart

@@ -8,8 +8,15 @@ import 'package:tests/data/sample_data.dart' as people;
 part 'database.g.dart';
 
 class Users extends Table {
+  /// The user id
   IntColumn get id => integer().autoIncrement()();
+
+  // The user name
   TextColumn get name => text()();
+
+  /// The users birth date
+  ///
+  /// Mapped from json `born_on`
   @JsonKey('born_on')
   DateTimeColumn get birthDate => dateTime()();
 

extras/integration_tests/tests/lib/database/database.g.dart

@@ -23,8 +23,13 @@ Map<String, dynamic> _$PreferencesToJson(Preferences instance) =>
 
 // ignore_for_file: unnecessary_brace_in_string_interps, unnecessary_this
 class User extends DataClass implements Insertable<User> {
+  /// The user id
   final int id;
   final String name;
+
+  /// The users birth date
+  ///
+  /// Mapped from json `born_on`
   final DateTime birthDate;
   final Uint8List profilePicture;
   final Preferences preferences;

moor_generator/lib/src/analyzer/dart/column_parser.dart

@@ -221,6 +221,9 @@ class ColumnParser {
       );
     }
 
+    final docString = getter.documentationComment?.tokens
+        ?.map((t) => t.toString())
+        ?.join('\n');
     return MoorColumn(
       type: columnType,
       dartGetterName: getter.name.name,
@@ -233,6 +236,7 @@ class ColumnParser {
       clientDefaultCode: clientDefaultExpression?.toSource(),
       typeConverter: converter,
       declaration: DartColumnDeclaration(element, base.step.file),
+      documentationComment: docString,
     );
   }
 

moor_generator/lib/src/model/column.dart

@@ -96,6 +96,11 @@ class MoorColumn implements HasDeclaration, HasType {
   @override
   final UsedTypeConverter typeConverter;
 
+  /// The documentation comment associated with this column
+  ///
+  /// Stored as a multi line string with leading triple-slashes `///` for every line
+  final String documentationComment;
+
   /// The column type from the dsl library. For instance, if a table has
   /// declared an `IntColumn`, the matching dsl column name would also be an
   /// `IntColumn`.
@@ -132,6 +137,7 @@ class MoorColumn implements HasDeclaration, HasType {
     this.clientDefaultCode,
     this.typeConverter,
     this.declaration,
+    this.documentationComment,
   });
 }
 

moor_generator/lib/src/writer/tables/data_class_writer.dart

@@ -22,6 +22,9 @@ class DataClassWriter {
 
     // write individual fields
     for (final column in table.columns) {
+      if (column.documentationComment != null) {
+        _buffer.write('${column.documentationComment}\n');
+      }
       final modifier = scope.options.fieldModifier;
       _buffer.write('$modifier ${column.dartTypeCode(scope.generationOptions)} '
           '${column.dartGetterName}; \n');

moor_generator/test/analyzer/dart/table_parser_test.dart

@@ -26,7 +26,11 @@ void main() {
       }
       
       class Users extends Table {
+        /// The user id
         IntColumn get id => integer().autoIncrement()();
+        /// The username
+        ///
+        /// The username must be between 6-32 characters
         TextColumn get name => text().named("user_name").withLength(min: 6, max: 32)();
         TextColumn get onlyMax => text().withLength(max: 100)();
         
@@ -187,6 +191,21 @@ void main() {
 
       expect(defaultsColumn.defaultArgument.toString(), 'currentDate');
     });
+
+    test('parses documentation comments', () async {
+      final table = await parse('Users');
+      final idColumn =
+          table.columns.singleWhere((col) => col.name.name == 'id');
+
+      final usernameColumn =
+          table.columns.singleWhere((col) => col.name.name == 'user_name');
+
+      expect(idColumn.documentationComment, '/// The user id');
+      expect(
+        usernameColumn.documentationComment,
+        '/// The username\n///\n/// The username must be between 6-32 characters',
+      );
+    });
   });
 
   test('parses custom primary keys', () async {