Support field documentation entries (description)

CHANGELOG.md

@@ -1,4 +1,7 @@
 # Changelog
+## [5.1.1] - 2021-08-27
+- Add support for adding `description` on fields to generate documentation entries
+- Fix self references (#82)
 ## [5.0.0] - 2021-07-27
 ### Breaking
 - include_if_null changed the default value to false

README.md

@@ -324,3 +324,16 @@ DateTimeConverter:
   type: json_converter
   path: converter/
 ```
+
+## 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
+```yaml
+UserModel:
+  path: webservice/user
+  converters:
+    - DateTimeConverter
+  properties:
+    description: The time at which the user has last updated his information
+    changedAt:
+      type: datetime
+```

lib/config/yml_generator_config.dart

@@ -99,6 +99,8 @@ class YmlGeneratorConfig {
           fields.add(EnumField(
             name: propertyKey,
             value: propertyValue == null ? null : propertyValue['value'],
+            description:
+                propertyValue == null ? null : propertyValue['description'],
           ));
         });
         models.add(EnumModel(
@@ -152,6 +154,9 @@ class YmlGeneratorConfig {
           property['include_if_null'] == true;
       final unknownEnumValue = property['unknown_enum_value'];
       final jsonKey = property['jsonKey'] ?? property['jsonkey'];
+      final description = property.containsKey('description')
+          ? property['description']!.toString()
+          : null;
       final type = property['type'];
       ItemType itemType;
 
@@ -192,6 +197,7 @@ class YmlGeneratorConfig {
         ignore: ignored,
         jsonKey: jsonKey,
         nonFinal: nonFinal,
+        description: description,
         includeIfNull: includeIfNull,
         unknownEnumValue: unknownEnumValue,
       );

lib/model/field.dart

@@ -11,6 +11,7 @@ class Field {
   final bool includeIfNull;
   final bool nonFinal;
   final String? unknownEnumValue;
+  final String? description;
 
   Field({
     required String name,
@@ -19,6 +20,7 @@ class Field {
     required this.ignore,
     required this.includeIfNull,
     required this.nonFinal,
+    this.description,
     this.unknownEnumValue,
     String? jsonKey,
   })  : serializedName = jsonKey ?? name,

lib/model/model/enum_model.dart

@@ -27,20 +27,24 @@ class EnumField {
   final String name;
   final String serializedName;
   final String? value;
+  final String? description;
 
   EnumField._({
     required this.name,
     required this.serializedName,
     required this.value,
+    required this.description,
   });
 
   factory EnumField({
     required String name,
     String? value,
+    String? description,
   }) =>
       EnumField._(
         name: name.toUpperCase(),
         serializedName: name,
         value: value,
+        description: description,
       );
 }

lib/writer/enum_model_writer.dart

@@ -14,6 +14,10 @@ class EnumModelWriter {
       final jsonValue = key.value == null || key.value?.isEmpty == null
           ? key.serializedName
           : key.value;
+      final description = key.description;
+      if (description != null) {
+        sb.writeln('  ///$description');
+      }
       sb
         ..writeln("  @JsonValue('$jsonValue')")
         ..writeln('  ${key.name},');

lib/writer/object_model_writer.dart

@@ -25,7 +25,8 @@ class ObjectModelWriter {
 
     jsonModel.fields.forEach((field) {
       final type = field.type;
-      if (!TypeChecker.isKnownDartType(type.name)) {
+      if (!TypeChecker.isKnownDartType(type.name) &&
+          type.name != jsonModel.name) {
         imports.addAll(_getImportsFromPath(type.name));
       }
       if (type is MapType && !TypeChecker.isKnownDartType(type.valueName)) {
@@ -62,6 +63,10 @@ class ObjectModelWriter {
     });
 
     jsonModel.fields.forEach((key) {
+      final description = key.description;
+      if (description != null) {
+        sb.writeln('  ///$description');
+      }
       sb.write("  @JsonKey(name: '${key.serializedName}'");
       if (key.isRequired) {
         sb.write(', required: true');

pubspec.yaml

@@ -1,6 +1,6 @@
 name: model_generator
 description: Dart tool to automaticly generate models from a yml file to speed up your development flow.
-version: 5.0.0
+version: 5.1.1
 homepage: https://github.com/icapps/flutter-model-generator
 
 environment:

test/config/yml_generator_config/object-all-types.txt

@@ -74,6 +74,7 @@ Person:
         items:
             type: datetime
     listObject:
+        description: A cool list of items
         type: array
         items:
             type: Address

test/writer/enum_model_writer/normal.txt

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

test/writer/enum_model_writer_test.dart

@@ -14,6 +14,7 @@ void main() {
           EnumField(
             name: 'MY_VALUE_1',
             value: 'MY_VALUE_1',
+            description: 'A good description of this field',
           ),
           EnumField(
             name: 'MY_VALUE_2',

test/writer/object_model_writer/normal/config.txt

@@ -3,4 +3,5 @@ Person:
   type: object
   properties:
     firstName:
+      description: A good description
       type: string

test/writer/object_model_writer/normal/output.txt

@@ -4,6 +4,7 @@ part 'person.g.dart';
 
 @JsonSerializable(explicitToJson: true)
 class Person {
+  ///A good description
   @JsonKey(name: 'firstName')
   final String? firstName;
 

test/writer/object_model_writer_test.dart

@@ -19,13 +19,13 @@ void main() {
         generateForGenerics: false,
         fields: [
           Field(
-            name: 'firstName',
-            type: StringType(),
-            isRequired: false,
-            ignore: false,
-            includeIfNull: true,
-            nonFinal: false,
-          ),
+              name: 'firstName',
+              type: StringType(),
+              isRequired: false,
+              ignore: false,
+              includeIfNull: true,
+              nonFinal: false,
+              description: 'A good description'),
         ],
         converters: [],
       );