Added model description comment generation

README.md

@@ -445,11 +445,12 @@ DateTimeConverter:
 
 ## Documentation support
 
-You can specify `description` on fields and on enum entries. This description will be used verbatim to generate a code comment for that field
+You can specify `description` on models, enum, fields and on enum entries. This description will be used verbatim to generate a code comment for that class/enum/field
 
 ```yaml
 UserModel:
   path: webservice/user
+  description: The model holding user data
   converters:
     - DateTimeConverter
   properties:

lib/config/yml_generator_config.dart

@@ -52,6 +52,7 @@ class YmlGeneratorConfig {
         }
       });
 
+      final description = value['description']?.toString();
       final dynamic properties = value['properties'];
       final YamlList? converters = value['converters'];
       final String? type = value['type'];
@@ -116,6 +117,7 @@ class YmlGeneratorConfig {
           fields: fields,
           extraImports: extraImports,
           extraAnnotations: extraAnnotations,
+          description: description,
         ));
       } else {
         final staticCreate = (value['static_create'] ?? false) == true;
@@ -141,6 +143,7 @@ class YmlGeneratorConfig {
           equalsAndHashCode: value['equals_and_hash_code'],
           explicitToJson: value['explicit_to_json'],
           generateToString: value['to_string'],
+          description: description,
         ));
       }
     });

lib/model/model/enum_model.dart

@@ -14,12 +14,14 @@ class EnumModel extends Model {
     List<String>? extraAnnotations,
     this.generateMap = false,
     this.generateExtensions = false,
+    String? description,
   }) : super(
           name: name,
           path: path,
           baseDirectory: baseDirectory,
           extraImports: extraImports,
           extraAnnotations: extraAnnotations,
+          description: description,
         );
 }
 

lib/model/model/model.dart

@@ -7,13 +7,15 @@ abstract class Model {
   final String name;
   final List<String>? extraImports;
   final List<String>? extraAnnotations;
+  final String? description;
 
   Model({
     required this.name,
     required String? path,
     required String? baseDirectory,
     required this.extraImports,
     required this.extraAnnotations,
+    this.description,
   })  : path = getPath(path),
         baseDirectory = getBaseDirectory(baseDirectory),
         fileName = getFileName(name);

lib/model/model/object_model.dart

@@ -23,11 +23,13 @@ class ObjectModel extends Model {
     this.explicitToJson,
     this.generateToString,
     this.staticCreate,
+    String? description,
   }) : super(
           name: name,
           path: path,
           baseDirectory: baseDirectory,
           extraAnnotations: extraAnnotations,
           extraImports: extraImports,
+          description: description,
         );
 }

lib/writer/enum_model_writer.dart

@@ -8,8 +8,14 @@ class EnumModelWriter {
   String write() {
     final sb = StringBuffer()
       ..writeln("import 'package:json_annotation/json_annotation.dart';")
-      ..writeln()
-      ..writeln('enum ${jsonModel.name} {');
+      ..writeln();
+
+    final modelDescription = jsonModel.description?.trim();
+    if (modelDescription != null && modelDescription.isNotEmpty) {
+      sb.writeln("///$modelDescription");
+    }
+
+    sb.writeln('enum ${jsonModel.name} {');
     jsonModel.fields?.forEach((key) {
       final jsonValue = key.value == null || key.value?.isEmpty == null
           ? key.serializedName

lib/writer/object_model_writer.dart

@@ -44,6 +44,12 @@ class ObjectModelWriter {
       ..writeln()
       ..writeln("part '${jsonModel.fileName}.g.dart';")
       ..writeln();
+
+    final modelDescription = jsonModel.description?.trim();
+    if (modelDescription != null && modelDescription.isNotEmpty) {
+      sb.writeln("///$modelDescription");
+    }
+
     if (jsonModel.explicitToJson ?? pubspecConfig.explicitToJson) {
       sb.writeln('@JsonSerializable(explicitToJson: true)');
     } else {

test/writer/enum_model_writer/normal-description.txt

@@ -0,0 +1,10 @@
+import 'package:json_annotation/json_annotation.dart';
+
+///A good description of this enum
+enum MyEnumModel {
+  ///A good description of this field
+  @JsonValue('MY_VALUE_1')
+  MY_VALUE_1,
+  @JsonValue('MY_VALUE_2')
+  MY_VALUE_2,
+}

test/writer/enum_model_writer_test.dart

@@ -120,5 +120,28 @@ void main() {
       );
       WriterTestHelper.testEnumModelWriter(model, 'custom-value-map-extension');
     });
+
+    test('Normal EnumModel with description', () {
+      final model = EnumModel(
+        name: 'MyEnumModel',
+        path: 'path_to_my_model',
+        baseDirectory: 'base_dir',
+        fields: [
+          EnumField(
+            name: 'MY_VALUE_1',
+            rawName: 'MY_VALUE_1',
+            value: 'MY_VALUE_1',
+            description: 'A good description of this field',
+          ),
+          EnumField(
+            name: 'MY_VALUE_2',
+            rawName: 'MY_VALUE_2',
+            value: 'MY_VALUE_2',
+          ),
+        ],
+        description: 'A good description of this enum',
+      );
+      WriterTestHelper.testEnumModelWriter(model, 'normal-description');
+    });
   });
 }

test/writer/object_model_writer/normal-with-description/config.txt

@@ -0,0 +1,9 @@
+Person:
+  path: user/person/
+  type: object
+  description: A good class description
+  properties:
+    firstName:
+      description: A good description
+      type: string
+      default_field: "'test'"

test/writer/object_model_writer/normal-with-description/output.txt

@@ -0,0 +1,20 @@
+import 'package:json_annotation/json_annotation.dart';
+
+part 'person.g.dart';
+
+///A good class description
+@JsonSerializable(explicitToJson: true)
+class Person {
+  ///A good description
+  @JsonKey(name: 'firstName')
+  final String? firstName;
+
+  const Person({
+    this.firstName = 'test',
+  });
+
+  factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);
+
+  Map<String, dynamic> toJson() => _$PersonToJson(this);
+
+}

test/writer/object_model_writer/normal-with-description/pubspec.txt

@@ -0,0 +1,4 @@
+name: model_generator_example
+
+model_generator:
+  config_path: model_generator/config.yaml

test/writer/object_model_writer_test.dart

@@ -821,6 +821,29 @@ void main() {
       );
       WriterTestHelper.testObjectModelWriter(model, 'default-field');
     });
+    test('Normal ObjectModelWriter with description', () {
+      final model = ObjectModel(
+          name: 'Person',
+          path: 'path_to_my_model',
+          baseDirectory: 'base_dir',
+          generateForGenerics: false,
+          staticCreate: false,
+          fields: [
+            Field(
+                name: 'firstName',
+                type: StringType(),
+                isRequired: false,
+                ignore: false,
+                includeIfNull: true,
+                ignoreEquality: false,
+                nonFinal: false,
+                defaultValue: '\'test\'',
+                description: 'A good description'),
+          ],
+          converters: [],
+          description: 'A good class description');
+      WriterTestHelper.testObjectModelWriter(model, 'normal-with-description');
+    });
     test('Normal ObjectModelWriter with default required field', () {
       final model = ObjectModel(
         name: 'Person',