Implement the first part of API review feedback.

All focusing on doc comments.

PiperOrigin-RevId: 310452162

Author: var-const

firestore/src/include/firebase/firestore.h

@@ -280,12 +280,17 @@ class Firestore {
    * any snapshot listeners or Get() calls will return results from cache, and
    * any write operations will be queued until network usage is re-enabled via a
    * call to EnableNetwork().
+   *
+   * If the network was already disabled, calling `DisableNetwork()` again is
+   * a no-op.
    */
   virtual Future<void> DisableNetwork();
 
   /**
    * Re-enables network usage for this instance after a prior call to
    * DisableNetwork().
+   *
+   * If the network is currently enabled, calling `EnableNetwork()` is a no-op.
    */
   virtual Future<void> EnableNetwork();
 
@@ -296,7 +301,7 @@ class Firestore {
    * used. Calling any other methods will result in an error.
    *
    * To restart after termination, simply create a new instance of `Firestore`
-   * with `Firestore::GetInstance`.
+   * with `Firestore::GetInstance()`.
    *
    * `Terminate()` does not cancel any pending writes and any tasks that are
    * awaiting a response from the server will not be resolved. The next time you

firestore/src/include/firebase/firestore/collection_reference.h

@@ -33,9 +33,9 @@ class CollectionReferenceInternal;
 class DocumentReference;
 
 /**
- * @brief A CollectionReference refers to a collection of documents location in
- * a Firestore database and can be used for adding documents, getting document
- * references, and querying for documents.
+ * @brief A CollectionReference can be used for adding documents, getting
+ * document references, and querying for documents (using the methods inherited
+ * from `Query`).
  *
  * @note Firestore classes are not meant to be subclassed except for use in test
  * mocks. Subclassing is not supported in production code and new SDK releases

firestore/src/include/firebase/firestore/document_reference.h

@@ -223,7 +223,9 @@ class DocumentReference {
    * @param[in] data A map of field / value pairs to update. Fields can contain
    * dots to reference nested fields within the document.
    *
-   * @return A Future that will be resolved when the write finishes.
+   * @return A Future that will be resolved when the client is online and the
+   * commit has completed against the server. The future will not resolve when
+   * the device is offline, though local changes will be visible immediately.
    */
   virtual Future<void> Update(const MapFieldValue& data);
 
@@ -235,7 +237,9 @@ class DocumentReference {
    *
    * @param[in] data A map from FieldPath to FieldValue to update.
    *
-   * @return A Future that will be resolved when the write finishes.
+   * @return A Future that will be resolved when the client is online and the
+   * commit has completed against the server. The future will not resolve when
+   * the device is offline, though local changes will be visible immediately.
    */
   virtual Future<void> Update(const MapFieldPathValue& data);
 

firestore/src/include/firebase/firestore/document_snapshot.h

@@ -191,7 +191,9 @@ class DocumentSnapshot {
    * @param stb Configures how server timestamps that have not yet been set to
    * their final value are returned from the snapshot (optional).
    *
-   * @return The value contained in the field.
+   * @return The value contained in the field. If the field does not exist in
+   * the document, then a `FieldValue` instance with `is_valid() == false` will
+   * be returned.
    */
   virtual FieldValue Get(
       const char* field,