From 3dd68d25bb8d4356d871a4b7d749113b54dddb4e Mon Sep 17 00:00:00 2001
From: Niels Pardon <par@zurich.ibm.com>
Date: Tue, 16 Jun 2026 15:56:04 +0200
Subject: [PATCH] docs(core): fix javadoc in MergeJoin

I used AI to generate missing javadoc comments for
`core/src/main/java/io/substrait/relation/physical/MergeJoin.java`.

Signed-off-by: Niels Pardon <par@zurich.ibm.com>
---
 .../relation/physical/MergeJoin.java          | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/core/src/main/java/io/substrait/relation/physical/MergeJoin.java b/core/src/main/java/io/substrait/relation/physical/MergeJoin.java
index 9664868bb..08a068e54 100644
--- a/core/src/main/java/io/substrait/relation/physical/MergeJoin.java
+++ b/core/src/main/java/io/substrait/relation/physical/MergeJoin.java
@@ -14,26 +14,57 @@
 import java.util.stream.Stream;
 import org.immutables.value.Value;
 
+/** A physical join relation that matches rows by merging two inputs sorted on their key columns. */
 @Value.Immutable
 public abstract class MergeJoin extends BiRel implements HasExtension {
 
+  /**
+   * Returns the left-side key fields the left input is sorted on.
+   *
+   * @return the left join keys
+   */
   public abstract List<FieldReference> getLeftKeys();
 
+  /**
+   * Returns the right-side key fields the right input is sorted on.
+   *
+   * @return the right join keys
+   */
   public abstract List<FieldReference> getRightKeys();
 
+  /**
+   * Returns the type of join to perform.
+   *
+   * @return the join type
+   */
   public abstract JoinType getJoinType();
 
+  /**
+   * Returns the filter applied to the join output after the join is performed, if any.
+   *
+   * @return the optional post-join filter
+   */
   public abstract Optional<Expression> getPostJoinFilter();
 
+  /** The kinds of join supported by a {@link MergeJoin} relation. */
   public enum JoinType {
+    /** Unspecified or unknown join type. */
     UNKNOWN(MergeJoinRel.JoinType.JOIN_TYPE_UNSPECIFIED),
+    /** Inner join: only matching left/right row pairs. */
     INNER(MergeJoinRel.JoinType.JOIN_TYPE_INNER),
+    /** Full outer join: all rows from both sides, with non-matches padded with nulls. */
     OUTER(MergeJoinRel.JoinType.JOIN_TYPE_OUTER),
+    /** Left outer join: all left rows, with non-matching right columns padded with nulls. */
     LEFT(MergeJoinRel.JoinType.JOIN_TYPE_LEFT),
+    /** Right outer join: all right rows, with non-matching left columns padded with nulls. */
     RIGHT(MergeJoinRel.JoinType.JOIN_TYPE_RIGHT),
+    /** Left semi join: left rows that have at least one match on the right. */
     LEFT_SEMI(MergeJoinRel.JoinType.JOIN_TYPE_LEFT_SEMI),
+    /** Right semi join: right rows that have at least one match on the left. */
     RIGHT_SEMI(MergeJoinRel.JoinType.JOIN_TYPE_RIGHT_SEMI),
+    /** Left anti join: left rows that have no match on the right. */
     LEFT_ANTI(MergeJoinRel.JoinType.JOIN_TYPE_LEFT_ANTI),
+    /** Right anti join: right rows that have no match on the left. */
     RIGHT_ANTI(MergeJoinRel.JoinType.JOIN_TYPE_RIGHT_ANTI);
 
     private MergeJoinRel.JoinType proto;
@@ -42,6 +73,13 @@ public enum JoinType {
       this.proto = proto;
     }
 
+    /**
+     * Returns the {@link JoinType} matching the given protobuf join type.
+     *
+     * @param proto the proto join type
+     * @return the matching join type
+     * @throws IllegalArgumentException if the type is not recognized
+     */
     public static JoinType fromProto(MergeJoinRel.JoinType proto) {
       for (JoinType v : values()) {
         if (v.proto == proto) {
@@ -51,6 +89,11 @@ public static JoinType fromProto(MergeJoinRel.JoinType proto) {
       throw new IllegalArgumentException("Unknown type: " + proto);
     }
 
+    /**
+     * Returns the protobuf representation of this join type.
+     *
+     * @return the proto join type
+     */
     public MergeJoinRel.JoinType toProto() {
       return proto;
     }
@@ -95,6 +138,11 @@ public <O, C extends VisitationContext, E extends Exception> O accept(
     return visitor.visit(this, context);
   }
 
+  /**
+   * Creates a builder for {@link MergeJoin}.
+   *
+   * @return a new builder
+   */
   public static ImmutableMergeJoin.Builder builder() {
     return ImmutableMergeJoin.builder();
   }