Improved documentation of the two new methods.

Signed-off-by: Johyn Papin <[email protected]>

Author: Johyn Papin

protobuf/lib/src/protobuf/field_set.dart

@@ -280,7 +280,9 @@ class _FieldSet {
     _setNonExtensionFieldUnchecked(meta, fi, value);
   }
 
-  /// Sets a non-repeated nullable field with error-checking.
+  /// Sets a non-repeated field with error-checking.
+  /// This method behaves like [_setField], except if `null` is passed as
+  /// value. In this case, [_clearField] will be called.
   ///
   /// Works for both extended and non-extended fields.
   /// Suitable for public API.

protobuf/lib/src/protobuf/generated_message.dart

@@ -403,6 +403,8 @@ abstract class GeneratedMessage {
   }
 
   /// Sets the value of a field by its [tagNumber].
+  /// This method should be used for optional fields when the nullable option
+  /// is set. When `null` is passed as value, the field is cleared.
   ///
   /// Throws an [ArgumentError] if [value] does not match the type associated
   /// with [tagNumber].