Tweak BuilderInfo and FieldInfo docs:

protobuf/lib/src/protobuf/builder_info.dart

@@ -8,12 +8,22 @@ part of protobuf;
 class BuilderInfo {
   /// The fully qualified name of this message.
   final String qualifiedMessageName;
+
+  /// Maps [FieldInfo.index]s to [FieldInfo]s.
   final List<FieldInfo> byIndex = <FieldInfo>[];
+
+  /// Maps [FieldInfo.tagNumber]s to [FieldInfo]s.
   final Map<int, FieldInfo> fieldInfo = <int, FieldInfo>{};
+
   final Map<String, FieldInfo> byTagAsString = <String, FieldInfo>{};
+
+  /// Maps [FieldInfo.name]s to [FieldInfo]s.
   final Map<String, FieldInfo> byName = <String, FieldInfo>{};
-  // Maps a tag number to the corresponding oneof index (if any).
+
+  /// Maps a tag number ([FieldInfo.tagNumber]) to the corresponding `oneof`
+  /// index (if any).
   final Map<int, int> oneofs = <int, int>{};
+
   bool hasExtensions = false;
   bool hasRequiredFields = true;
   List<FieldInfo>? _sortedByTag;
@@ -267,7 +277,7 @@ class BuilderInfo {
     return i?.valueOf;
   }
 
-  /// The FieldInfo for each field in tag number order.
+  /// The [FieldInfo] for each field in tag number order.
   List<FieldInfo> get sortedByTag => _sortedByTag ??= _computeSortedByTag();
 
   /// The message name. Also see [qualifiedMessageName].

protobuf/lib/src/protobuf/field_info.dart

@@ -8,44 +8,67 @@ part of protobuf;
 class FieldInfo<T> {
   FrozenPbList<T>? _emptyList;
 
-  /// Name of this field as the `json_name` reported by protoc.
-  ///
-  /// This will typically be in camel case.
+  /// Name of this field as the `json_name` reported by protoc. Example:
+  /// ```proto
+  /// message Msg {
+  ///   int32 foo_name = 1 [json_name = "barName"];
+  /// }
+  /// ```
+  /// Here `name` of the field is `barName`. When `json_name` is not specified
+  /// in the proto definition, this is the camelCase version of the field name.
+  /// In the example above, without the `json_name` field option, `name` would
+  /// be `"fooName"`.
   final String name;
 
-  /// The name of this field as written in the proto-definition.
-  ///
+  /// Name of this field as written in the proto definition. Example:
+  /// ```proto
+  /// message SearchRequest {
+  ///   ...
+  ///   int32 result_per_page = 3;
+  /// }
+  /// ```
+  /// `protoName` for the `result_per_page` field above is `"result_per_page"`.
   /// This will typically consist of words separated with underscores.
   final String protoName;
 
+  /// Field number as specified in the proto definition. Example:
+  /// ```proto
+  /// message SearchRequest {
+  ///   ...
+  ///   int32 result_per_page = 3;
+  /// }
+  /// ```
+  /// `tagNumber` of `result_per_page` field is 3.
   final int tagNumber;
-  final int? index; // index of the field's value. Null for extensions.
+
+  /// Index of the field in [_FieldSet._values] list of this field's message.
+  /// `null` for extensions.
+  final int? index;
+
+  /// Type of this field. See `field_type.dart`.
   final int type;
 
-  // Constructs the default value of a field.
-  // (Only used for repeated fields where check is null.)
+  /// Constructs the default value of a field. For repeated fields, only used
+  /// when the `check` property is null.
   final MakeDefaultFunc? makeDefault;
 
-  // Creates an empty message or group when decoding a message.
-  // Not used for other types.
-  // see GeneratedMessage._getEmptyMessage
+  /// Only available in fields with message type. Creates an empty message or
+  /// group when decoding a message.
   final CreateBuilderFunc? subBuilder;
 
-  // List of all enum enumValues.
-  // (Not used for other types.)
+  /// Only available in enum fields. List of all enum values.
   final List<ProtobufEnum>? enumValues;
 
-  // Default enum value, if type is a PbList<ProtobufEnum> or a
-  // PbMap<[anything], ProtobufEnum>.
+  /// Only available in enum fields. Default enum value or a
+  /// `PbMap<[anything], ProtobufEnum>`.
   final ProtobufEnum? defaultEnumValue;
 
-  // Looks up the enum value given its integer code.
-  // (Not used for other types.)
-  // see GeneratedMessage._getValueOfFunc
+  /// Only available in enum fields. Looks up the enum value given its integer
+  /// code.
   final ValueOfFunc? valueOf;
 
-  // Verifies an item being added to a repeated field
-  // (Not used for non-repeated fields.)
+  /// Only available in repeated fields. Verifies an item being added to a
+  /// repeated field.
   final CheckFunc<T>? check;
 
   FieldInfo(this.name, this.tagNumber, this.index, this.type,
@@ -105,8 +128,8 @@ class FieldInfo<T> {
   bool get isEnum => _isEnum(type);
   bool get isMapField => _isMapField(type);
 
-  /// Returns a read-only default value for a field.
-  /// (Unlike getField, doesn't create a repeated field.)
+  /// Returns a read-only default value for a field. Unlike
+  /// [GeneratedMessage.getField], doesn't create a repeated field.
   dynamic get readonlyDefault {
     if (isRepeated) {
       return _emptyList ??= FrozenPbList._([]);