Add a new field Library.generatedByComment to support emitting 'gen…

…erated by' comments. (#441)

add a Library.generatedByComment field

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.9.0
+
+* Add `Library.generatedByComment` to support emitting 'generated by' comments.
+
 ## 4.8.0
 
 * Add `Expression.operatorSubtract`

README.md

@@ -103,9 +103,7 @@ run from the snapshot instead of from source to avoid problems with deleted
 files. These steps must be run without deleting the source files.
 
 ```bash
-$ dart run build_runner generate-build-script
-$ dart compile kernel .dart_tool/build/entrypoint/build.dart
-$ dart .dart_tool/build/entrypoint/build.dill build --delete-conflicting-outputs
+./tool/regenerate.sh 
 ```
 
 [build_runner]: https://pub.dev/packages/build_runner

lib/src/emitter.dart

@@ -483,6 +483,12 @@ class DartEmitter extends Object
       output.writeln();
     }
 
+    if (spec.generatedByComment != null) {
+      output
+        ..writeln('// ${spec.generatedByComment}')
+        ..writeln();
+    }
+
     if (spec.ignoreForFile.isNotEmpty) {
       final ignores = spec.ignoreForFile.toList()..sort();
       final lines = ['// ignore_for_file: ${ignores.first}'];

lib/src/specs/library.dart

@@ -30,6 +30,12 @@ abstract class Library
   /// Line comments to place at the start of the library.
   BuiltList<String> get comments;
 
+  /// A comment indicating the tool this library was generated by.
+  ///
+  /// This is typically of the form `Generated by xxx.`; it should exclude
+  /// leading line comment characters.
+  String? get generatedByComment;
+
   /// A list of analysis issues to ignore (`ignore_for_file: ...`).
   BuiltList<String> get ignoreForFile;
 
@@ -59,6 +65,8 @@ abstract class LibraryBuilder
   ListBuilder<Directive> directives = ListBuilder<Directive>();
 
   ListBuilder<String> comments = ListBuilder<String>();
+  String? generatedByComment;
   ListBuilder<String> ignoreForFile = ListBuilder<String>();
+
   String? name;
 }

pubspec.yaml

@@ -1,5 +1,5 @@
 name: code_builder
-version: 4.8.0
+version: 4.9.0
 description: >-
   A fluent, builder-based library for generating valid Dart code
 repository: https://github.com/dart-lang/code_builder

test/specs/library_test.dart

@@ -53,6 +53,23 @@ void main() {
       );
     });
 
+    test('should emit a source file with a generated-by comment', () {
+      expect(
+        Library(
+          (b) => b
+            ..generatedByComment = 'Generated by fooBar.'
+            ..body.add(
+              Class((b) => b..name = 'Foo'),
+            ),
+        ),
+        equalsDart(r'''
+          // Generated by fooBar.
+
+          class Foo { }
+        ''', DartEmitter(allocator: Allocator())),
+      );
+    });
+
     test('should emit a source file with ignore comments', () {
       expect(
         Library(
@@ -93,6 +110,30 @@ void main() {
       );
     });
 
+    test('should emit with line comments, generated-by, and ignore-for-file',
+        () {
+      expect(
+        Library(
+          (b) => b
+            ..comments.add('Generic copyright statement.')
+            ..generatedByComment = 'Generated by fooBar.'
+            ..ignoreForFile.add('sort_constructors_first')
+            ..body.add(
+              Class((b) => b..name = 'Foo'),
+            ),
+        ),
+        equalsDart(r'''
+          // Generic copyright statement.
+
+          // Generated by fooBar.
+
+          // ignore_for_file: sort_constructors_first
+
+          class Foo { }
+        ''', DartEmitter(allocator: Allocator())),
+      );
+    });
+
     test('should emit a source file with manual imports', () {
       expect(
         Library((b) => b

tool/regenerate.sh

@@ -0,0 +1,7 @@
+# Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+# for details. All rights reserved. Use of this source code is governed by a
+# BSD-style license that can be found in the LICENSE file.
+
+dart run build_runner generate-build-script
+dart compile kernel .dart_tool/build/entrypoint/build.dart
+dart .dart_tool/build/entrypoint/build.dill build --delete-conflicting-outputs