Document null handling behavior in declareField to match REST

Add comprehensive javadoc explaining null handling behavior:

1. If value is null:
   - Parser and consumer NOT called (no-op)
   - Matches REST behavior when field not present in JSON

2. If value is not null:
   - Parser transforms the value
   - Consumer called with transformed value

3. If parser returns null:
   - Consumer STILL called with null
   - Setter is responsible for null validation (matches REST)

This clarifies that the null-check behavior perfectly mirrors REST's
ObjectParser pattern, where absent fields result in no parser/consumer
invocation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yiyuabc

modules/transport-grpc/src/main/java/org/opensearch/transport/grpc/proto/request/common/ObjectParserProtoUtils.java

@@ -61,6 +61,15 @@ private ObjectParserProtoUtils() {
      * extracted from proto, so the parser is used for transformation only. For simple fields that
      * need no transformation, use {@link Function#identity()}.
      *
+     * <p><b>Null handling (matches REST):</b>
+     * <ul>
+     *   <li>If value is null: parser and consumer are NOT called (no-op), matching REST behavior
+     *       when a field is not present in JSON</li>
+     *   <li>If value is not null: parser transforms it, then consumer is called with the result</li>
+     *   <li>If parser returns null: consumer is STILL called - the setter is responsible for
+     *       null validation, just like REST</li>
+     * </ul>
+     *
      * @param builder The builder to set the field on
      * @param consumer The consumer to set the field value (e.g., Builder::field, Builder::missing)
      * @param value The proto value (if null, the field is not set)
@@ -87,10 +96,13 @@ public static <T, P, V> void declareField(
         if (parser == null) {
             throw new IllegalArgumentException("[parser] is required");
         }
+        // If value is null, do nothing - matches REST behavior when field not present in JSON
         if (value != null) {
             try {
                 V transformedValue = parser.apply(value);
-                consumer.accept(builder, transformedValue);  // Setter validates
+                // Note: Even if transformedValue is null, we still call consumer
+                // The setter is responsible for null validation, just like REST
+                consumer.accept(builder, transformedValue);
             } catch (IllegalArgumentException e) {
                 throw e; // Re-throw validation exceptions
             } catch (Exception e) {