Compiler: generate doc comments

protoc_plugin/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 21.1.0-wip
+
+* Experimental support for generating comments. Use the `generate_comments` option. ([#161])
+
+[#161]: https://github.com/google/protobuf.dart/issues/161
+
 ## 21.0.2
 
 * Fix missing protobuf import in generated grpc files. ([#844])

protoc_plugin/Makefile

@@ -88,7 +88,7 @@ $(TEST_PROTO_LIBS): $(PLUGIN_SRC) $(TEST_PROTO_SRCS)
 	dart format $(TEST_PROTO_DIR)
 
 update-pregenerated: $(PLUGIN_PATH) $(PREGENERATED_SRCS)
-	protoc --dart_out=lib/src/generated -Iprotos --plugin=protoc-gen-dart=$(realpath $(PLUGIN_PATH)) $(PREGENERATED_SRCS)
+	protoc --dart_out=generate_comments:lib/src/generated -Iprotos --plugin=protoc-gen-dart=$(realpath $(PLUGIN_PATH)) $(PREGENERATED_SRCS)
 	rm lib/src/generated/descriptor.pb{json,server}.dart
 	rm lib/src/generated/dart_options.pb{enum,json,server}.dart
 	rm lib/src/generated/plugin.pb{json,server}.dart

protoc_plugin/lib/src/enum_generator.dart

@@ -103,6 +103,10 @@ class EnumGenerator extends ProtobufContainer {
   static const int _enumValueTag = 2;
 
   void generate(IndentingWriter out) {
+    final comment = fileGen?.commentBlock(fieldPath!);
+    if (comment != null) {
+      out.println(comment);
+    }
     out.addAnnotatedBlock(
         'class $classname extends $protobufImportPrefix.ProtobufEnum {',
         '}\n', [

protoc_plugin/lib/src/generated/dart_options.pb.dart

@@ -13,6 +13,8 @@ import 'dart:core' as $core;
 
 import 'package:protobuf/protobuf.dart' as $pb;
 
+/// A mixin that can be used in the 'with' clause of the generated Dart class
+/// for a proto message.
 class DartMixin extends $pb.GeneratedMessage {
   factory DartMixin() => create();
   DartMixin._() : super();
@@ -53,6 +55,7 @@ class DartMixin extends $pb.GeneratedMessage {
       _defaultInstance ??= $pb.GeneratedMessage.$_defaultFor<DartMixin>(create);
   static DartMixin? _defaultInstance;
 
+  /// The name of the mixin class.
   @$pb.TagNumber(1)
   $core.String get name => $_getSZ(0);
   @$pb.TagNumber(1)
@@ -65,6 +68,8 @@ class DartMixin extends $pb.GeneratedMessage {
   @$pb.TagNumber(1)
   void clearName() => clearField(1);
 
+  /// A URI pointing to the Dart library that defines the mixin.
+  /// The generated Dart code will use this in an import statement.
   @$pb.TagNumber(2)
   $core.String get importFrom => $_getSZ(1);
   @$pb.TagNumber(2)
@@ -77,6 +82,9 @@ class DartMixin extends $pb.GeneratedMessage {
   @$pb.TagNumber(2)
   void clearImportFrom() => clearField(2);
 
+  /// The name of another mixin to be applied ahead of this one.
+  /// The generated class for the message will inherit from all mixins
+  /// in the parent chain.
   @$pb.TagNumber(3)
   $core.String get parent => $_getSZ(2);
   @$pb.TagNumber(3)
@@ -90,6 +98,7 @@ class DartMixin extends $pb.GeneratedMessage {
   void clearParent() => clearField(3);
 }
 
+/// Defines additional Dart imports to be used with messages in this file.
 class Imports extends $pb.GeneratedMessage {
   factory Imports() => create();
   Imports._() : super();
@@ -129,6 +138,14 @@ class Imports extends $pb.GeneratedMessage {
       _defaultInstance ??= $pb.GeneratedMessage.$_defaultFor<Imports>(create);
   static Imports? _defaultInstance;
 
+  ///  Mixins to be used on messages in this file.
+  ///  These mixins are in addition to internally defined mixins (e.g PbMapMixin)
+  ///  and may override them.
+  ///
+  ///  Warning: mixins are experimental. The protoc Dart plugin doesn't check
+  ///  for name conflicts between mixin class members and generated class members,
+  ///  so the generated code may contain errors. Therefore, running dartanalyzer
+  ///  on the generated file is a good idea.
   @$pb.TagNumber(1)
   $core.List<DartMixin> get mixins => $_getList(0);
 }