diff --git a/protobuf/lib/src/protobuf/field_set.dart b/protobuf/lib/src/protobuf/field_set.dart
index 09201fe4c..55d0ec575 100644
--- a/protobuf/lib/src/protobuf/field_set.dart
+++ b/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.
diff --git a/protobuf/lib/src/protobuf/generated_message.dart b/protobuf/lib/src/protobuf/generated_message.dart
index 0af2d49f0..c51e5c31a 100644
--- a/protobuf/lib/src/protobuf/generated_message.dart
+++ b/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].