feat: support docs for libraries (dart-archive/code_builder#444)

Signed-off-by: Nikolas Rimikis <[email protected]> Co-authored-by: Nikolas Rimikis <[email protected]>
dart-lang · Dec 28, 2023 · 2edf94e · 2edf94e
1 parent 7ec7f52
commit 2edf94e
Show file tree

Hide file tree

Showing 7 changed files with 59 additions and 7 deletions.
diff --git a/pkgs/code_builder/AUTHORS b/pkgs/code_builder/AUTHORS
@@ -3,4 +3,5 @@
 #
 #   Name/Organization <email address>
 
-Google Inc.
+Nikolas Rimikis <[email protected]>
+Google Inc.
diff --git a/pkgs/code_builder/CHANGELOG.md b/pkgs/code_builder/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 4.10.0-wip
+
+* Add `Library.docs` to support emitting doc comments on libraries.
+
 ## 4.9.0
 
 * Add `Library.generatedByComment` to support emitting 'generated by' comments.

diff --git a/pkgs/code_builder/lib/src/emitter.dart b/pkgs/code_builder/lib/src/emitter.dart
@@ -512,15 +512,15 @@ class DartEmitter extends Object
       }
     }
 
+    spec.docs.forEach(output.writeln);
     for (var a in spec.annotations) {
       visitAnnotation(a, output);
     }
     if (spec.name != null) {
       output.write('library ${spec.name!};');
-    } else if (spec.annotations.isNotEmpty) {
+    } else if (spec.annotations.isNotEmpty || spec.docs.isNotEmpty) {
       // An explicit _unnamed_ library directive is only required if there are
-      // annotations or doc comments on the library (though doc comments are not
-      // currently supported in code_builder).
+      // annotations or doc comments on the library.
       output.write('library;');
     }
 

diff --git a/pkgs/code_builder/lib/src/specs/library.dart b/pkgs/code_builder/lib/src/specs/library.dart
@@ -8,6 +8,7 @@ import 'package:meta/meta.dart';
 
 import '../base.dart';
 import '../mixins/annotations.dart';
+import '../mixins/dartdoc.dart';
 import '../visitors.dart';
 import 'directive.dart';
 import 'expression.dart';
@@ -16,14 +17,17 @@ part 'library.g.dart';
 
 @immutable
 abstract class Library
-    with HasAnnotations
+    with HasAnnotations, HasDartDocs
     implements Built<Library, LibraryBuilder>, Spec {
   factory Library([void Function(LibraryBuilder) updates]) = _$Library;
   Library._();
 
   @override
   BuiltList<Expression> get annotations;
 
+  @override
+  BuiltList<String> get docs;
+
   BuiltList<Directive> get directives;
   BuiltList<Spec> get body;
 
@@ -53,14 +57,17 @@ abstract class Library
 }
 
 abstract class LibraryBuilder
-    with HasAnnotationsBuilder
+    with HasAnnotationsBuilder, HasDartDocsBuilder
     implements Builder<Library, LibraryBuilder> {
   factory LibraryBuilder() = _$LibraryBuilder;
   LibraryBuilder._();
 
   @override
   ListBuilder<Expression> annotations = ListBuilder<Expression>();
 
+  @override
+  ListBuilder<String> docs = ListBuilder<String>();
+
   ListBuilder<Spec> body = ListBuilder<Spec>();
   ListBuilder<Directive> directives = ListBuilder<Directive>();
 

diff --git a/pkgs/code_builder/lib/src/specs/library.g.dart b/pkgs/code_builder/lib/src/specs/library.g.dart
diff --git a/pkgs/code_builder/pubspec.yaml b/pkgs/code_builder/pubspec.yaml
@@ -1,5 +1,5 @@
 name: code_builder
-version: 4.9.0
+version: 4.10.0-wip
 description: >-
   A fluent, builder-based library for generating valid Dart code
 repository: https://github.com/dart-lang/code_builder

diff --git a/pkgs/code_builder/test/specs/library_test.dart b/pkgs/code_builder/test/specs/library_test.dart
@@ -292,5 +292,22 @@ void main() {
         ''', DartEmitter(allocator: Allocator())),
       );
     });
+
+    test('should emit an unnamed library source file with documentation', () {
+      expect(
+        Library(
+          (b) => b
+            ..docs.addAll(
+              const [
+                '/// My favorite library.',
+              ],
+            ),
+        ),
+        equalsDart(r'''
+        /// My favorite library.
+        library;
+      '''),
+      );
+    });
   });
 }