From 93c7d13f8e40ba236c5410d21b283378f998edcf Mon Sep 17 00:00:00 2001 From: Nicola Verbeeck Date: Wed, 17 Nov 2021 08:00:04 +0100 Subject: [PATCH 1/2] Added model description comment generation Fixes #87 --- lib/config/yml_generator_config.dart | 3 +++ lib/model/model/enum_model.dart | 2 ++ lib/model/model/model.dart | 2 ++ lib/model/model/object_model.dart | 2 ++ lib/writer/enum_model_writer.dart | 10 ++++++-- lib/writer/object_model_writer.dart | 6 +++++ .../enum_model_writer/normal-description.txt | 10 ++++++++ test/writer/enum_model_writer_test.dart | 23 +++++++++++++++++++ .../normal-with-description/config.txt | 9 ++++++++ .../normal-with-description/output.txt | 20 ++++++++++++++++ .../normal-with-description/pubspec.txt | 4 ++++ test/writer/object_model_writer_test.dart | 23 +++++++++++++++++++ 12 files changed, 112 insertions(+), 2 deletions(-) create mode 100644 test/writer/enum_model_writer/normal-description.txt create mode 100644 test/writer/object_model_writer/normal-with-description/config.txt create mode 100644 test/writer/object_model_writer/normal-with-description/output.txt create mode 100644 test/writer/object_model_writer/normal-with-description/pubspec.txt diff --git a/lib/config/yml_generator_config.dart b/lib/config/yml_generator_config.dart index 1f52e1a..13f4c35 100644 --- a/lib/config/yml_generator_config.dart +++ b/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, )); } }); diff --git a/lib/model/model/enum_model.dart b/lib/model/model/enum_model.dart index db612ef..079ff54 100644 --- a/lib/model/model/enum_model.dart +++ b/lib/model/model/enum_model.dart @@ -14,12 +14,14 @@ class EnumModel extends Model { List? extraAnnotations, this.generateMap = false, this.generateExtensions = false, + String? description, }) : super( name: name, path: path, baseDirectory: baseDirectory, extraImports: extraImports, extraAnnotations: extraAnnotations, + description: description, ); } diff --git a/lib/model/model/model.dart b/lib/model/model/model.dart index cf6fefb..6c6c975 100644 --- a/lib/model/model/model.dart +++ b/lib/model/model/model.dart @@ -7,6 +7,7 @@ abstract class Model { final String name; final List? extraImports; final List? extraAnnotations; + final String? description; Model({ required this.name, @@ -14,6 +15,7 @@ abstract class Model { required String? baseDirectory, required this.extraImports, required this.extraAnnotations, + this.description, }) : path = getPath(path), baseDirectory = getBaseDirectory(baseDirectory), fileName = getFileName(name); diff --git a/lib/model/model/object_model.dart b/lib/model/model/object_model.dart index 71aa197..97a8a2f 100644 --- a/lib/model/model/object_model.dart +++ b/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, ); } diff --git a/lib/writer/enum_model_writer.dart b/lib/writer/enum_model_writer.dart index 96f06d4..2a58233 100644 --- a/lib/writer/enum_model_writer.dart +++ b/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 diff --git a/lib/writer/object_model_writer.dart b/lib/writer/object_model_writer.dart index 2bbbb59..36452b6 100644 --- a/lib/writer/object_model_writer.dart +++ b/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 { diff --git a/test/writer/enum_model_writer/normal-description.txt b/test/writer/enum_model_writer/normal-description.txt new file mode 100644 index 0000000..991f37b --- /dev/null +++ b/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, +} diff --git a/test/writer/enum_model_writer_test.dart b/test/writer/enum_model_writer_test.dart index d189949..e6b5acf 100644 --- a/test/writer/enum_model_writer_test.dart +++ b/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'); + }); }); } diff --git a/test/writer/object_model_writer/normal-with-description/config.txt b/test/writer/object_model_writer/normal-with-description/config.txt new file mode 100644 index 0000000..569984a --- /dev/null +++ b/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'" \ No newline at end of file diff --git a/test/writer/object_model_writer/normal-with-description/output.txt b/test/writer/object_model_writer/normal-with-description/output.txt new file mode 100644 index 0000000..ab6ba86 --- /dev/null +++ b/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 json) => _$PersonFromJson(json); + + Map toJson() => _$PersonToJson(this); + +} diff --git a/test/writer/object_model_writer/normal-with-description/pubspec.txt b/test/writer/object_model_writer/normal-with-description/pubspec.txt new file mode 100644 index 0000000..95f3114 --- /dev/null +++ b/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 diff --git a/test/writer/object_model_writer_test.dart b/test/writer/object_model_writer_test.dart index a124061..70009b4 100644 --- a/test/writer/object_model_writer_test.dart +++ b/test/writer/object_model_writer_test.dart @@ -821,5 +821,28 @@ 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'); + }); }); } From 923c712c9597cbad3cb09ecb678aeeb04b2f90a4 Mon Sep 17 00:00:00 2001 From: Nicola Verbeeck Date: Wed, 17 Nov 2021 08:04:40 +0100 Subject: [PATCH 2/2] Updated docs --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 74befe5..bbbace3 100755 --- a/README.md +++ b/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: