Javadoc updates (#4143)

* Update documentation for SendOptions

* Update docs in EventPosition and PartitionProperties.

* Add @see to documentation.

eventhubs/client/azure-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventData.java

@@ -44,6 +44,8 @@
  * Serializing a received {@link EventData} with AMQP sections other than ApplicationProperties (with primitive Java
  * types) and Data section is not supported.
  * </p>
+ *
+ * @see EventHubProducer
  */
 public class EventData implements Comparable<EventData> {
     /*

eventhubs/client/azure-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventHubConsumerOptions.java

@@ -14,6 +14,9 @@
 /**
  * The baseline set of options that can be specified when creating a {@link EventHubConsumer} to configure its
  * behavior.
+ *
+ * @see EventHubConsumer
+ * @see EventHubClient#createConsumer(String, String, EventPosition, EventHubConsumerOptions)
  */
 public class EventHubConsumerOptions implements Cloneable {
     /**

eventhubs/client/azure-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventHubProducerOptions.java

@@ -9,6 +9,9 @@
 
 /**
  * The set of options that can be specified when creating an {@link EventHubProducer} to configure its behavior.
+ *
+ * @see EventHubProducer
+ * @see EventHubClient#createProducer(EventHubProducerOptions)
  */
 public class EventHubProducerOptions implements Cloneable {
     private String partitionId;

eventhubs/client/azure-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventHubProperties.java

@@ -10,6 +10,8 @@
  * Holds information about Event Hubs which can come handy while performing data-plane operations like
  * {@link EventHubClient#createConsumer(String, String, EventPosition)} and
  * {@link EventHubClient#createConsumer(String, String, EventPosition, EventHubConsumerOptions)}.
+ *
+ * @see EventHubClient
  */
 public final class EventHubProperties {
     private final String path;

eventhubs/client/azure-eventhubs/src/main/java/com/azure/messaging/eventhubs/EventPosition.java

@@ -15,8 +15,10 @@
 import static com.azure.core.amqp.MessageConstant.SEQUENCE_NUMBER_ANNOTATION_NAME;
 
 /**
- * Defines a position of an {@link EventData} in the event hub partition.
- * The position can be an Offset, Sequence Number, or EnqueuedTime.
+ * Defines a position of an {@link EventData} in the Event Hub partition. The position can be an offset, sequence
+ * number, or enqueued time.
+ *
+ * @see EventHubConsumer
  */
 public final class EventPosition {
     /**
@@ -25,9 +27,9 @@ public final class EventPosition {
     private static final String START_OF_STREAM = "-1";
 
     /**
-     * This is a constant defined to represent the current end of a partition stream in EventHub.
-     * This can be used as an offset argument in receiver creation to start receiving from the latest
-     * event, instead of a specific offset or point in time.
+     * This is a constant defined to represent the current end of a partition stream in EventHub. This can be used as an
+     * offset argument in receiver creation to start receiving from the latest event, instead of a specific offset or
+     * point in time.
      */
     private static final String END_OF_STREAM = "@latest";
 
@@ -45,19 +47,19 @@ private EventPosition(boolean isInclusive) {
     }
 
     /**
-     * Returns the position for the start of a stream. Provide this position in receiver creation
-     * to start receiving from the first available (earliest) event in the partition.
+     * Corresponds to the location of the first event present in the partition. Use this position to begin receiving
+     * from the first event that was enqueued in the partition which has not expired due to the retention policy.
      *
-     * @return An {@link EventPosition} set to the start of an Event Hubs stream.
+     * @return An {@link EventPosition} set to the start of an Event Hub stream.
      */
     public static EventPosition earliest() {
         return EARLIEST;
     }
 
     /**
      * Corresponds to the end of the partition, where no more events are currently enqueued. Use this position to begin
-     * receiving from the next event to be enqueued in the partition after an {@link EventHubConsumer} is created with this
-     * position.
+     * receiving from the next event to be enqueued in the partition after an {@link EventHubConsumer} is created with
+     * this position.
      *
      * @return An {@link EventPosition} set to the end of an Event Hubs stream and listens for new events.
      */
@@ -82,6 +84,12 @@ public static EventPosition fromEnqueuedTime(Instant enqueuedDateTime) {
     /**
      * Corresponds to the event in the partition at the provided offset, inclusive of that event.
      *
+     * <p>
+     * The offset is the relative position for event in the context of the stream. The offset should not be considered a
+     * stable value, as the same offset may refer to a different event as events reach the age limit for retention and
+     * are no longer visible within the stream.
+     * </p>
+     *
      * @param offset The offset of the event within that partition.
      * @return An {@link EventPosition} object.
      */
@@ -90,12 +98,12 @@ public static EventPosition fromOffset(String offset) {
     }
 
     /**
-     * Creates a position to an event in the partition at the provided offset. If {@code isInclusive} is true, the
-     * event with the same offset is returned. Otherwise, the next event is received.
+     * Creates a position to an event in the partition at the provided offset. If {@code isInclusive} is true, the event
+     * with the same offset is returned. Otherwise, the next event is received.
      *
      * @param offset The offset of an event with respect to its relative position in the
-     * @param isInclusive If true, the event with the {@code offset} is included; otherwise, the next event will be
-     * received.
+     * @param isInclusive If true, the event with the {@code offset} is included; otherwise, the next event will
+     *         be received.
      * @return An {@link EventPosition} object.
      */
     public static EventPosition fromOffset(String offset, boolean isInclusive) {
@@ -107,8 +115,8 @@ public static EventPosition fromOffset(String offset, boolean isInclusive) {
     }
 
     /**
-     * Creates a position at the given sequence number. The specified event will not be included. Instead, the next
-     * event is returned.
+     * Creates a position to an event in the partition at the provided sequence number. The event with the sequence
+     * number will not be included. Instead, the next event is returned.
      *
      * @param sequenceNumber is the sequence number of the event.
      * @return An {@link EventPosition} object.
@@ -122,8 +130,8 @@ public static EventPosition fromSequenceNumber(long sequenceNumber) {
      * number is returned. Otherwise, the next event in the sequence is received.
      *
      * @param sequenceNumber is the sequence number of the event.
-     * @param isInclusive If true, the event with the {@code sequenceNumber} is included; otherwise, the next event will
-     * be received.
+     * @param isInclusive If true, the event with the {@code sequenceNumber} is included; otherwise, the next
+     *         event will be received.
      * @return An {@link EventPosition} object.
      */
     public static EventPosition fromSequenceNumber(long sequenceNumber, boolean isInclusive) {

eventhubs/client/azure-eventhubs/src/main/java/com/azure/messaging/eventhubs/PartitionProperties.java

@@ -6,7 +6,7 @@
 import java.time.Instant;
 
 /**
- * Contains runtime information about an Event Hub partition.
+ * A set of information for a single partition of an Event Hub.
  */
 public final class PartitionProperties {
     private final String eventHubPath;
@@ -18,13 +18,13 @@ public final class PartitionProperties {
     private final boolean isEmpty;
 
     PartitionProperties(
-            final String eventHubPath,
-            final String id,
-            final long beginningSequenceNumber,
-            final long lastEnqueuedSequenceNumber,
-            final String lastEnqueuedOffset,
-            final Instant lastEnqueuedTime,
-            final boolean isEmpty) {
+        final String eventHubPath,
+        final String id,
+        final long beginningSequenceNumber,
+        final long lastEnqueuedSequenceNumber,
+        final String lastEnqueuedOffset,
+        final Instant lastEnqueuedTime,
+        final boolean isEmpty) {
         this.eventHubPath = eventHubPath;
         this.id = id;
         this.beginningSequenceNumber = beginningSequenceNumber;
@@ -35,9 +35,9 @@ public final class PartitionProperties {
     }
 
     /**
-     * Gets the Event Hub path for this partition.
+     * Gets the Event Hub path that contains the partition, relative to the Event Hubs namespace that contains it.
      *
-     * @return The Event Hub path for this partition.
+     * @return The Event Hub path that contains the partition.
      */
     public String eventHubPath() {
         return this.eventHubPath;
@@ -73,6 +73,12 @@ public long lastEnqueuedSequenceNumber() {
     /**
      * Gets the offset of the last enqueued message in the partition's stream.
      *
+     * <p>
+     * The offset is the relative position for event in the context of the stream. The offset should not be considered
+     * a stable value, as the same offset may refer to a different event as events reach the age limit for retention and
+     * are no longer visible within the stream.
+     * </p>
+     *
      * @return the offset of the last enqueued message in the partition's stream.
      */
     public String lastEnqueuedOffset() {
@@ -89,9 +95,9 @@ public Instant lastEnqueuedTime() {
     }
 
     /**
-     * Indicates whether or not there are events in the partition.
+     * Indicates whether or not the partition is currently empty.
      *
-     * @return true if there are no events, and false otherwise.
+     * @return {@code true} if there are no events, and {@code false} otherwise.
      */
     public boolean isEmpty() {
         return this.isEmpty;

eventhubs/client/azure-eventhubs/src/main/java/com/azure/messaging/eventhubs/SendOptions.java

@@ -4,8 +4,10 @@
 package com.azure.messaging.eventhubs;
 
 /**
- * The set of options that can be specified when sending a set of events to configure how the event data is packaged
- * into batches.
+ * The set of options that can be specified when sending a set of events to influence the way in which events are sent
+ * to the Event Hubs service.
+ *
+ * @see EventHubProducer
  */
 public class SendOptions {
     private int maximumSizeInBytes;
@@ -23,7 +25,7 @@ public SendOptions() {
      * will be thrown and the send operation will fail.
      *
      * @param maximumSizeInBytes The maximum size to allow for a single batch of events.
-     * @return The updated EventBatchingOptions object.
+     * @return The updated {@link SendOptions} object.
      */
     SendOptions maximumSizeInBytes(int maximumSizeInBytes) {
         this.maximumSizeInBytes = maximumSizeInBytes;
@@ -41,11 +43,20 @@ int maximumSizeInBytes() {
     }
 
     /**
-     * Sets a partition key on an event batch, which tells the Event Hubs service to send all events with that partition
-     * routing key to the same partition.
+     * Sets a hashing key to be provided for the batch of events, which instructs the Event Hubs service map this key to
+     * a specific partition but allowing the service to choose an arbitrary, partition for this batch of events and any
+     * other batches using the same partition hashing key.
      *
-     * @param partitionKey The label of an event batch.
-     * @return The updated EventBatchingOptions object.
+     * The selection of a partition is stable for a given partition hashing key. Should any other batches of events be
+     * sent using the same exact partition hashing key, the Event Hubs service will route them all to the same
+     * partition.
+     *
+     * This should be specified only when there is a need to group events by partition, but there is flexibility into
+     * which partition they are routed. If ensuring that a batch of events is sent only to a specific partition, it is
+     * recommended that the identifier of the position be specified directly when sending the batch.
+     *
+     * @param partitionKey The partition hashing key to associate with the event or batch of events.
+     * @return The updated {@link SendOptions} object.
      */
     public SendOptions partitionKey(String partitionKey) {
         this.partitionKey = partitionKey;
@@ -56,7 +67,7 @@ public SendOptions partitionKey(String partitionKey) {
      * Gets the partition routing key on an event batch. If specified, tells the Event Hubs service that these events
      * belong to the same group and should belong to the same partition.
      *
-     * @return The partition key on an event batch.
+     * @return The partition hashing key to associate with the event or batch of events.
      */
     public String partitionKey() {
         return partitionKey;