From 60d99aacf42696cf930b5d0b5e7a9710158389f4 Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Sun, 15 Sep 2024 01:30:52 -0400 Subject: [PATCH 01/11] changes work on local project. Documented new field. --- source_gen/lib/src/builder.dart | 35 +++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/source_gen/lib/src/builder.dart b/source_gen/lib/src/builder.dart index bc8b4257..d6d59980 100644 --- a/source_gen/lib/src/builder.dart +++ b/source_gen/lib/src/builder.dart @@ -35,6 +35,9 @@ class _Builder extends Builder { final String _header; + /// Whether to include or emit the gen part descriptions. Defaults to true. + final bool _writeDescriptions; + /// Whether to allow syntax errors in input libraries. final bool allowSyntaxErrors; @@ -51,6 +54,7 @@ class _Builder extends Builder { String generatedExtension = '.g.dart', List additionalOutputExtensions = const [], String? header, + bool? writeDescriptions, this.allowSyntaxErrors = false, BuilderOptions? options, }) : _generatedExtension = generatedExtension, @@ -61,6 +65,7 @@ class _Builder extends Builder { ...additionalOutputExtensions, ], }), + _writeDescriptions = (writeDescriptions ?? true), _header = (header ?? defaultFileHeader).trim() { if (_generatedExtension.isEmpty || !_generatedExtension.startsWith('.')) { throw ArgumentError.value( @@ -153,16 +158,19 @@ class _Builder extends Builder { } for (var item in generatedOutputs) { - contentBuffer - ..writeln() - ..writeln(_headerLine) - ..writeAll( - LineSplitter.split(item.generatorDescription) - .map((line) => '// $line\n'), - ) - ..writeln(_headerLine) - ..writeln() - ..writeln(item.output); + if (_writeDescriptions) { + contentBuffer + ..writeln() + ..writeln(_headerLine) + ..writeAll( + LineSplitter.split(item.generatorDescription) + .map((line) => '// $line\n'), + ) + ..writeln(_headerLine) + ..writeln(); + } + + contentBuffer.writeln(item.output); } var genPartContent = contentBuffer.toString(); @@ -225,6 +233,7 @@ class SharedPartBuilder extends _Builder { super.formatOutput, super.additionalOutputExtensions, super.allowSyntaxErrors, + super.writeDescriptions, }) : super( generatedExtension: '.$partId.g.part', header: '', @@ -265,6 +274,10 @@ class PartBuilder extends _Builder { /// [formatOutput] is called to format the generated code. Defaults to /// [DartFormatter.format]. /// + /// If [writeDescriptions] is false, then no generated descriptions will be + /// embeded into the generated out file. The default is true, which includes + /// the name of the dart files/parts/libraries which were used to generate. + /// /// [header] is used to specify the content at the top of each generated file. /// If `null`, the content of [defaultFileHeader] is used. /// If [header] is an empty `String` no header is added. @@ -279,6 +292,7 @@ class PartBuilder extends _Builder { String generatedExtension, { super.formatOutput, super.additionalOutputExtensions, + super.writeDescriptions, super.header, super.allowSyntaxErrors, super.options, @@ -316,6 +330,7 @@ class LibraryBuilder extends _Builder { super.formatOutput, super.generatedExtension, super.additionalOutputExtensions, + super.writeDescriptions, super.header, super.allowSyntaxErrors, super.options, From 30e1481fae89c5f2a4bced25c4c1f3e667bae0fb Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Sun, 15 Sep 2024 01:35:40 -0400 Subject: [PATCH 02/11] Added test --- source_gen/test/builder_test.dart | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/source_gen/test/builder_test.dart b/source_gen/test/builder_test.dart index 55239ad3..293c9c7f 100644 --- a/source_gen/test/builder_test.dart +++ b/source_gen/test/builder_test.dart @@ -84,6 +84,25 @@ void main() { ); }); + test('Omits generated comments if writeDescriptions is explicitly false', + () async { + final srcs = _createPackageStub(); + final builder = LibraryBuilder( + const CommentGenerator(), + header: '', + writeDescriptions: false, + ); + await testBuilder( + builder, + srcs, + generateFor: {'$_pkgName|lib/test_lib.dart'}, + outputs: { + '$_pkgName|lib/test_lib.g.dart': + decodedMatches(isNot(startsWith('// ***'))), + }, + ); + }); + test('Expect no error when multiple generators used on nonstandalone builder', () async { expect( From 10984cb3fc939a521925972ff846ea37ae4b2c08 Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Fri, 20 Sep 2024 16:33:40 -0400 Subject: [PATCH 03/11] address issue found in CICD test --- source_gen/lib/src/builder.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source_gen/lib/src/builder.dart b/source_gen/lib/src/builder.dart index d6d59980..99b66301 100644 --- a/source_gen/lib/src/builder.dart +++ b/source_gen/lib/src/builder.dart @@ -65,7 +65,7 @@ class _Builder extends Builder { ...additionalOutputExtensions, ], }), - _writeDescriptions = (writeDescriptions ?? true), + _writeDescriptions = writeDescriptions ?? true, _header = (header ?? defaultFileHeader).trim() { if (_generatedExtension.isEmpty || !_generatedExtension.startsWith('.')) { throw ArgumentError.value( From 73ace4eccc4822f675f4549a5e56a6f483c76c2a Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Sat, 21 Sep 2024 00:38:36 -0400 Subject: [PATCH 04/11] update change log --- source_gen/CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source_gen/CHANGELOG.md b/source_gen/CHANGELOG.md index f79caa5c..8ded0f43 100644 --- a/source_gen/CHANGELOG.md +++ b/source_gen/CHANGELOG.md @@ -1,3 +1,6 @@ +## 2.1.0-wip +- `LibraryBuilder`, `PartBuilder`, `SharedPartBuilder`, can now take an optional `writeDescriptions` boolean. When set to `false`, headers and generator descriptions for the files will not be included in the builder output. + ## 2.0.0-wip - **Breaking Change**: Change `formatOutput` function to accept a language From 5ff6f20c25b00f4afdc5a9c2cf823944f8d39be9 Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Sat, 21 Sep 2024 00:39:01 -0400 Subject: [PATCH 05/11] update minor version --- source_gen/pubspec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source_gen/pubspec.yaml b/source_gen/pubspec.yaml index 66b5c831..48ab8a73 100644 --- a/source_gen/pubspec.yaml +++ b/source_gen/pubspec.yaml @@ -1,5 +1,5 @@ name: source_gen -version: 2.0.0-wip +version: 2.1.0-wip description: >- Source code generation builders and utilities for the Dart build system repository: https://github.com/dart-lang/source_gen/tree/master/source_gen From 18ec1676e4e1bc52f5f95ca3195c7c5e3aa8412b Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Sat, 21 Sep 2024 00:40:00 -0400 Subject: [PATCH 06/11] grammar fix in changelog --- source_gen/CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source_gen/CHANGELOG.md b/source_gen/CHANGELOG.md index 8ded0f43..dfd4a11e 100644 --- a/source_gen/CHANGELOG.md +++ b/source_gen/CHANGELOG.md @@ -1,5 +1,5 @@ ## 2.1.0-wip -- `LibraryBuilder`, `PartBuilder`, `SharedPartBuilder`, can now take an optional `writeDescriptions` boolean. When set to `false`, headers and generator descriptions for the files will not be included in the builder output. +- `LibraryBuilder`, `PartBuilder`, and `SharedPartBuilder` now take an optional `writeDescriptions` boolean. When set to `false`, headers and generator descriptions for the files will not be included in the builder output. ## 2.0.0-wip From e70bc3c28920fd9b31242a30d9996d1edf8fe929 Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Mon, 23 Sep 2024 19:16:54 -0400 Subject: [PATCH 07/11] Update source_gen/CHANGELOG.md Co-authored-by: Jacob MacDonald --- source_gen/CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/source_gen/CHANGELOG.md b/source_gen/CHANGELOG.md index dfd4a11e..0e87a44f 100644 --- a/source_gen/CHANGELOG.md +++ b/source_gen/CHANGELOG.md @@ -1,4 +1,5 @@ ## 2.1.0-wip + - `LibraryBuilder`, `PartBuilder`, and `SharedPartBuilder` now take an optional `writeDescriptions` boolean. When set to `false`, headers and generator descriptions for the files will not be included in the builder output. ## 2.0.0-wip From be049b97432c8b72b26325e4d3271f4722e6ab37 Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Mon, 23 Sep 2024 20:02:26 -0400 Subject: [PATCH 08/11] Rewrote docs for writeDescriptions to match the style of the other fields. Corrected writeDescriptions=false test to catch specific values, both with and without a header present. Added an additional test to sanity check when writeDescriptions=true. --- source_gen/lib/src/builder.dart | 20 ++++++++++-- source_gen/test/builder_test.dart | 53 +++++++++++++++++++++++++++++-- 2 files changed, 68 insertions(+), 5 deletions(-) diff --git a/source_gen/lib/src/builder.dart b/source_gen/lib/src/builder.dart index 99b66301..13df806c 100644 --- a/source_gen/lib/src/builder.dart +++ b/source_gen/lib/src/builder.dart @@ -227,6 +227,12 @@ class SharedPartBuilder extends _Builder { /// /// [allowSyntaxErrors] indicates whether to allow syntax errors in input /// libraries. + /// + /// [writeDescriptions] adds comments to the output used to separate the + /// sections of the file generated from different generators, and reveals + /// which generator produced the following output. + /// If `null`, [writeDescriptions] is set to true which is the default value. + /// If [writeDescriptions] is false, no generator descriptions are added. SharedPartBuilder( super.generators, String partId, { @@ -274,9 +280,11 @@ class PartBuilder extends _Builder { /// [formatOutput] is called to format the generated code. Defaults to /// [DartFormatter.format]. /// - /// If [writeDescriptions] is false, then no generated descriptions will be - /// embeded into the generated out file. The default is true, which includes - /// the name of the dart files/parts/libraries which were used to generate. + /// [writeDescriptions] adds comments to the output used to separate the + /// sections of the file generated from different generators, and reveals + /// which generator produced the following output. + /// If `null`, [writeDescriptions] is set to true which is the default value. + /// If [writeDescriptions] is false, no generator descriptions are added. /// /// [header] is used to specify the content at the top of each generated file. /// If `null`, the content of [defaultFileHeader] is used. @@ -319,6 +327,12 @@ class LibraryBuilder extends _Builder { /// [formatOutput] is called to format the generated code. Defaults to /// using the standard [DartFormatter]. /// + /// [writeDescriptions] adds comments to the output used to separate the + /// sections of the file generated from different generators, and reveals + /// which generator produced the following output. + /// If `null`, [writeDescriptions] is set to true which is the default value. + /// If [writeDescriptions] is false, no generator descriptions are added. + /// /// [header] is used to specify the content at the top of each generated file. /// If `null`, the content of [defaultFileHeader] is used. /// If [header] is an empty `String` no header is added. diff --git a/source_gen/test/builder_test.dart b/source_gen/test/builder_test.dart index 293c9c7f..2b904fa0 100644 --- a/source_gen/test/builder_test.dart +++ b/source_gen/test/builder_test.dart @@ -89,16 +89,65 @@ void main() { final srcs = _createPackageStub(); final builder = LibraryBuilder( const CommentGenerator(), - header: '', writeDescriptions: false, ); + + // With default header await testBuilder( builder, srcs, generateFor: {'$_pkgName|lib/test_lib.dart'}, outputs: { '$_pkgName|lib/test_lib.g.dart': - decodedMatches(isNot(startsWith('// ***'))), + decodedMatches(startsWith(defaultFileHeader)), + }, + ); + + // Explicitly empty header + final builderEmptyHeader = LibraryBuilder( + const CommentGenerator(), + header: '', + writeDescriptions: false, + ); + + const expected = ''' +// Code for "class Person" +// Code for "class Customer" +'''; + + await testBuilder( + builderEmptyHeader, + srcs, + generateFor: {'$_pkgName|lib/test_lib.dart'}, + outputs: { + '$_pkgName|lib/test_lib.g.dart': decodedMatches(startsWith(expected)), + }, + ); + }); + + test('When writeDescriptions is true, generated comments are present', + () async { + final srcs = _createPackageStub(); + + // Null value for writeDescriptions resolves to true + final builder = LibraryBuilder( + const CommentGenerator(), + // We omit header to inspect the generator descriptions + header: '', + ); + + const expected = ''' +// ************************************************************************** +// CommentGenerator +// ************************************************************************** +'''; + + await testBuilder( + builder, + srcs, + generateFor: {'$_pkgName|lib/test_lib.dart'}, + outputs: { + '$_pkgName|lib/test_lib.g.dart': decodedMatches(contains(expected)), }, ); }); From 7dc7699debcc579ca5850e5f27cbd3e497cd1e69 Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Mon, 23 Sep 2024 20:06:47 -0400 Subject: [PATCH 09/11] removed useless test case --- source_gen/test/builder_test.dart | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/source_gen/test/builder_test.dart b/source_gen/test/builder_test.dart index 2b904fa0..d6a6b76b 100644 --- a/source_gen/test/builder_test.dart +++ b/source_gen/test/builder_test.dart @@ -87,21 +87,6 @@ void main() { test('Omits generated comments if writeDescriptions is explicitly false', () async { final srcs = _createPackageStub(); - final builder = LibraryBuilder( - const CommentGenerator(), - writeDescriptions: false, - ); - - // With default header - await testBuilder( - builder, - srcs, - generateFor: {'$_pkgName|lib/test_lib.dart'}, - outputs: { - '$_pkgName|lib/test_lib.g.dart': - decodedMatches(startsWith(defaultFileHeader)), - }, - ); // Explicitly empty header final builderEmptyHeader = LibraryBuilder( From 99716494f49fcb943b030ab7bfbee2e671d38688 Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Tue, 24 Sep 2024 12:25:01 -0400 Subject: [PATCH 10/11] 2.0.0-wip is not yet published. Merging the changelog note for this feature into it and removing the bumped version 2.0.1-wip. --- source_gen/CHANGELOG.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/source_gen/CHANGELOG.md b/source_gen/CHANGELOG.md index 0e87a44f..a69d855d 100644 --- a/source_gen/CHANGELOG.md +++ b/source_gen/CHANGELOG.md @@ -1,7 +1,3 @@ -## 2.1.0-wip - -- `LibraryBuilder`, `PartBuilder`, and `SharedPartBuilder` now take an optional `writeDescriptions` boolean. When set to `false`, headers and generator descriptions for the files will not be included in the builder output. - ## 2.0.0-wip - **Breaking Change**: Change `formatOutput` function to accept a language @@ -14,6 +10,7 @@ - Support all the glob quotes. - Require `analyzer: ^6.9.0` - Require Dart 3.5.0 +- `LibraryBuilder`, `PartBuilder`, and `SharedPartBuilder` now take an optional `writeDescriptions` boolean. When set to `false`, headers and generator descriptions for the files will not be included in the builder output. ## 1.5.0 From ca4b1228ae081402054973600a38a828a518d7aa Mon Sep 17 00:00:00 2001 From: TheMaverickProgrammer <91709+TheMaverickProgrammer@users.noreply.github.com> Date: Tue, 24 Sep 2024 12:26:17 -0400 Subject: [PATCH 11/11] revert pubspec yaml to unpublish 2.0.0-wip --- source_gen/pubspec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source_gen/pubspec.yaml b/source_gen/pubspec.yaml index 48ab8a73..66b5c831 100644 --- a/source_gen/pubspec.yaml +++ b/source_gen/pubspec.yaml @@ -1,5 +1,5 @@ name: source_gen -version: 2.1.0-wip +version: 2.0.0-wip description: >- Source code generation builders and utilities for the Dart build system repository: https://github.com/dart-lang/source_gen/tree/master/source_gen