Review comments and javadoc style fixes.

Author: kannanjgithub

api/src/main/java/io/grpc/NameResolver.java

@@ -238,8 +238,9 @@ public final void onAddresses(
      * Handles updates on resolved addresses and attributes.  If
      * {@link ResolutionResult#getAddressesOrError()} is empty, {@link #onError(Status)} will be
      * called.
-     * New implementations should prefer overriding onResult2. This method exists to facilitate
-     * older implementations using {@link Listener} to migrate to {@link Listener2}.
+     *
+     * <p>Newer NameResolver implementations should prefer calling onResult2. This method exists to
+     * facilitate older {@link Listener} implementations to migrate to {@link Listener2}.
      *
      * @param resolutionResult the resolved server addresses, attributes, and Service Config.
      * @since 1.21.0
@@ -249,9 +250,10 @@ public final void onAddresses(
     /**
      * Handles a name resolving error from the resolver. The listener is responsible for eventually
      * invoking {@link NameResolver#refresh()} to re-attempt resolution.
-     * New implementations should prefer overriding onResult2 which will have the address
-     * resolution error in {@link ResolutionResult}'s addressesOrError. This method exists to
-     * facilitate older implementations using {@link Listener} to migrate to {@link Listener2}.
+     *
+     * <p>New NameResolver implementations should prefer calling onResult2 which will have the
+     * address resolution error in {@link ResolutionResult}'s addressesOrError. This method exists
+     * to facilitate older implementations using {@link Listener} to migrate to {@link Listener2}.
      *
      * @param error a non-OK status
      * @since 1.21.0
@@ -260,8 +262,9 @@ public final void onAddresses(
     public abstract void onError(Status error);
 
     /**
-     * Handles updates on resolved addresses and attributes. Must be called from
-     * {@link SynchronizationContext}.
+     * Handles updates on resolved addresses and attributes. Must be called from the same
+     * {@link SynchronizationContext} available in {@link NameResolver.Args} that is passed
+     * from the channel.
      *
      * @param resolutionResult the resolved server addresses or error in address resolution,
      *     attributes, and Service Config or error