[c++] Adding doc comments for EventListener java files

Making some edits to comments based on other CL reviews.

PiperOrigin-RevId: 292645766

Author: Googler

firestore/src/android/field_value_android.cc

@@ -132,7 +132,7 @@ FieldValueInternal::FieldValueInternal(std::vector<FieldValue> value)
   JNIEnv* env = firestore_->app()->GetJNIEnv();
   jmethodID add_method = util::array_list::GetMethodId(util::array_list::kAdd);
   for (const FieldValue& element : value) {
-    // ArrayList.Add() always returns true, which we have no use of.
+    // ArrayList.Add() always returns true, which we have no use for.
     env->CallBooleanMethod(obj_, add_method, element.internal_->obj_);
   }
   CheckAndClearJniExceptions(env);
@@ -147,7 +147,7 @@ FieldValueInternal::FieldValueInternal(MapFieldValue value)
   for (const auto& kv : value) {
     jobject key = env->NewStringUTF(kv.first.c_str());
     // Map::Put() returns previously associated value or null, which we have no
-    // use of.
+    // use for.
     env->CallObjectMethod(obj_, put_method, key, kv.second.internal_->obj_);
     env->DeleteLocalRef(key);
   }

firestore/src_java/com/google/firebase/firestore/internal/cpp/DocumentEventListener.java

@@ -5,24 +5,43 @@
 import com.google.firebase.firestore.EventListener;
 import com.google.firebase.firestore.FirebaseFirestoreException;
 
-/** Implements Firestore EventListener<DocumentSnapshot> by redirecting calls into C++. */
+/**
+ * Implements Firestore {@code
+ * firebase::firestore::EventListener<firebase::firestore::DocumentSnapshot>} by redirecting calls
+ * into the C++ equivalent.
+ */
 public class DocumentEventListener extends CppEventListener
     implements EventListener<DocumentSnapshot> {
-  /** Construct a DocumentEventListener. Parameters are C++ pointers. */
+  /**
+   * Constructs a DocumentEventListener. Ownership of the underlying EventListener can be
+   * transferred when creating the {@code ListenerRegistration}. If the ListenerRegistration owns
+   * the EventListener, it will de-allocate the EventListener in its destructor.
+   *
+   * <p>Passing in 0 is considered a null pointer and will result in {@code onEvent} becoming a
+   * no-op.
+   *
+   * @param cppFirestoreObject Pointer to a {@code firebase::firestore::Firestore}.
+   * @param cppListenerObject Pointer to a {@code
+   *     firebase::firestore::EventListener<firebase::firestore::DocumentSnapshot>}.
+   */
   public DocumentEventListener(long cppFirestoreObject, long cppListenerObject) {
     super(cppFirestoreObject, cppListenerObject);
   }
 
   @Override
   public synchronized void onEvent(
       @Nullable DocumentSnapshot value, @Nullable FirebaseFirestoreException error) {
-    if (cppFirestoreObject != 0 && cppListenerObject != 0) {
       nativeOnEvent(cppFirestoreObject, cppListenerObject, value, error);
-    }
   }
 
   /**
-   * This native function is implemented in the Firestore C++ library (event_listener_android.cc).
+   * Interprets the {@code listenerObject} as a {@code
+   * firebase::firestore::EventListener<DocumentSnapshot>} and invokes the listener's {@code
+   * OnEvent} method with the {@code error} and {@code DocumentSnapshot} created by interpreting the
+   * {@code firestoreObject} as a {@code firebase::firestore::Firestore}.
+   *
+   * <p>This native method is implemented in the Firestore C++ library {@code
+   * event_listener_android.cc}.
    */
   private static native void nativeOnEvent(
       long firestoreObject,

firestore/src_java/com/google/firebase/firestore/internal/cpp/Dummy.java

@@ -1,7 +1,7 @@
 package com.google.firebase.firestore.internal.cpp;
 
 /**
- * Place-holder dummy Java class for Firestore C++ Android clients.
+ * Place-holder dummy Java class for Firestore C++ Android clients. This is currently being used to
+ * prevent Tricorder errors since we do not have desktop support yet.
  */
-public class Dummy {
-}
+public class Dummy {}

firestore/src_java/com/google/firebase/firestore/internal/cpp/QueryEventListener.java

@@ -5,23 +5,42 @@
 import com.google.firebase.firestore.FirebaseFirestoreException;
 import com.google.firebase.firestore.QuerySnapshot;
 
-/** Implements Firestore EventListener<QuerySnapshot> by redirecting calls into C++. */
+/**
+ * Implements Firestore {@code
+ * firebase::firestore::EventListener<firebase::firestore::QuerySnapshot>} by redirecting calls into
+ * the C++ equivalent.
+ */
 public class QueryEventListener extends CppEventListener implements EventListener<QuerySnapshot> {
-  /** Construct a QueryEventListener. Parameters are C++ pointers. */
+  /**
+   * Constructs a QueryEventListener. Ownership of the underlying EventListener can be transferred
+   * when creating the {@code ListenerRegistration}. If the ListenerRegistration owns the
+   * EventListener, it will de-allocate the EventListener in its destructor.
+   *
+   * <p>Passing in 0 is considered a null pointer and will result in {@code onEvent} becoming a
+   * no-op.
+   *
+   * @param cppFirestoreObject Pointer to a {@code firebase::firestore::Firestore}.
+   * @param cppListenerObject Pointer to a {@code
+   *     firebase::firestore::EventListener<firebase::firestore::QuerySnapshot>}.
+   */
   public QueryEventListener(long cppFirestoreObject, long cppListenerObject) {
     super(cppFirestoreObject, cppListenerObject);
   }
 
   @Override
   public synchronized void onEvent(
       @Nullable QuerySnapshot value, @Nullable FirebaseFirestoreException error) {
-    if (cppFirestoreObject != 0 && cppListenerObject != 0) {
       nativeOnEvent(cppFirestoreObject, cppListenerObject, value, error);
-    }
   }
 
   /**
-   * This native function is implemented in the Firestore C++ library (event_listener_android.cc).
+   * Interprets the {@code listenerObject} as a {@code
+   * firebase::firestore::EventListener<QuerySnapshot>} and invokes the listener's {@code OnEvent}
+   * method with the {@code error} and {@code QuerySnapshot} created by interpreting the {@code
+   * firestoreObject} as a {@code firebase::firestore::Firestore}.
+   *
+   * <p>This native method is implemented in the Firestore C++ library {@code
+   * event_listener_android.cc}.
    */
   private static native void nativeOnEvent(
       long firestoreObject,

firestore/src_java/com/google/firebase/firestore/internal/cpp/VoidEventListener.java

@@ -11,7 +11,7 @@ public class VoidEventListener extends CppEventListener implements Runnable {
    * when creating the {@code ListenerRegistration}. If the ListenerRegistration owns the
    * EventListener, it will de-allocate the EventListener in its destructor.
    *
-   * <p>Passing in 0 is considered a null pointer and will result in an early return.
+   * <p>Passing in 0 is considered a null pointer and will result in {@code run} becoming a no-op.
    *
    * @param cppListenerObject Pointer to a {@code firebase::firestore::EventListener<void>}.
    */
@@ -29,6 +29,9 @@ public void run() {
    * invokes the listener's {@code OnEvent} method with {@code Error::Ok}. The EventListener will
    * never be passed anything other than Ok because VoidEventListener can only be used in
    * circumstances where the callback can't fail.
+   *
+   * <p>This native method is implemented in the Firestore C++ library {@code
+   * event_listener_android.cc}.
    */
   private static native void nativeOnEvent(long listenerObject);
 }