From 2a5d473175289f8958ec4e988a9549ec4a47cb6d Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@gmail.com>
Date: Thu, 26 Sep 2024 11:10:59 -0400
Subject: [PATCH] Improve docs for when SDAM Monitoring events are dispatched

https://jira.mongodb.org/browse/PHPC-2449
---
 .../driver/monitoring/sdamsubscriber/serverchanged.xml |  3 ++-
 .../driver/monitoring/sdamsubscriber/serverclosed.xml  |  4 ++--
 .../driver/monitoring/sdamsubscriber/serveropening.xml |  4 ++--
 .../monitoring/sdamsubscriber/topologychanged.xml      |  3 ++-
 .../monitoring/sdamsubscriber/topologyclosed.xml       | 10 ++++++++++
 .../monitoring/sdamsubscriber/topologyopening.xml      |  9 +++++++++
 .../mongodb/driver/monitoring/serverchangedevent.xml   |  4 +++-
 .../mongodb/driver/monitoring/serverclosedevent.xml    |  3 ++-
 .../driver/monitoring/serverheartbeatfailedevent.xml   |  5 ++++-
 .../driver/monitoring/serverheartbeatstartedevent.xml  |  5 ++++-
 .../monitoring/serverheartbeatsucceededevent.xml       |  5 ++++-
 .../mongodb/driver/monitoring/serveropeningevent.xml   |  3 ++-
 .../mongodb/driver/monitoring/topologychangedevent.xml |  4 +++-
 .../mongodb/driver/monitoring/topologyclosedevent.xml  | 10 ++++++++++
 .../mongodb/driver/monitoring/topologyopeningevent.xml |  9 +++++++++
 15 files changed, 68 insertions(+), 13 deletions(-)

diff --git a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serverchanged.xml b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serverchanged.xml
index 71e3540442b1..a01210bda05d 100644
--- a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serverchanged.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serverchanged.xml
@@ -15,7 +15,8 @@
   </methodsynopsis>
   <para>
    If the subscriber is registered, this method is called when a server's
-   description changes.
+   description changes. For example, a server's type changing from secondary to
+   primary would cause its server description to change.
   </para>
  </refsect1>
 
diff --git a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serverclosed.xml b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serverclosed.xml
index d5c0b690dd8b..e3c3bda8030b 100644
--- a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serverclosed.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serverclosed.xml
@@ -14,8 +14,8 @@
    <methodparam><type>MongoDB\Driver\Monitoring\ServerClosedEvent</type><parameter>event</parameter></methodparam>
   </methodsynopsis>
   <para>
-   If the subscriber is registered, this method is called when a server is
-   closed.
+   If the subscriber is registered, this method is called when an existing
+   server is removed from the topology.
   </para>
  </refsect1>
 
diff --git a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serveropening.xml b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serveropening.xml
index c02eeb42e132..515f18526d24 100644
--- a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serveropening.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/serveropening.xml
@@ -14,8 +14,8 @@
    <methodparam><type>MongoDB\Driver\Monitoring\ServerOpeningEvent</type><parameter>event</parameter></methodparam>
   </methodsynopsis>
   <para>
-   If the subscriber is registered, this method is called when a server is
-   opened.
+   If the subscriber is registered, this method is called when a new server is
+   added to the topology.
   </para>
  </refsect1>
 
diff --git a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologychanged.xml b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologychanged.xml
index 190c9c5f72a7..d2b0dc0ae46f 100644
--- a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologychanged.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologychanged.xml
@@ -15,7 +15,8 @@
   </methodsynopsis>
   <para>
    If the subscriber is registered, this method is called when the topology's
-   description changes.
+   description changes. For example, a topology discovering a new replica set
+   primary would cause its topology description to change.
   </para>
  </refsect1>
 
diff --git a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologyclosed.xml b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologyclosed.xml
index 189bb9c0dc23..1bd9a0a820e7 100644
--- a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologyclosed.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologyclosed.xml
@@ -17,6 +17,16 @@
    If the subscriber is registered, this method is called when the topology is
    closed.
   </para>
+  <note>
+   <simpara>
+    Due to the driver's
+    <link linkend="mongodb.connection-handling">connection handling and persistence</link>
+    behavior, this event can only be observed when a
+    <classname>MongoDB\Driver\Manager</classname> is created with the
+    <literal>"disableClientPersistence"</literal> driver option and freed before
+    request shutdown (RSHUTDOWN).
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologyopening.xml b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologyopening.xml
index 8eef42e2d2fd..0b72f2e09d76 100644
--- a/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologyopening.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/sdamsubscriber/topologyopening.xml
@@ -17,6 +17,15 @@
    If the subscriber is registered, this method is called when the topology is
    opened.
   </para>
+  <note>
+   <simpara>
+    Due to the driver's
+    <link linkend="mongodb.connection-handling">connection handling and persistence</link>
+    behavior, this event may not be observed if a
+    <classname>MongoDB\Driver\Manager</classname> uses a previously persisted
+    <link xlink:href="&url.mongodb.libmongoc;">libmongoc</link> client.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/mongodb/mongodb/driver/monitoring/serverchangedevent.xml b/reference/mongodb/mongodb/driver/monitoring/serverchangedevent.xml
index b478b8a1855e..16eda2fddce6 100644
--- a/reference/mongodb/mongodb/driver/monitoring/serverchangedevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/serverchangedevent.xml
@@ -13,7 +13,9 @@
    &reftitle.intro;
    <para>
     The <classname>MongoDB\Driver\Monitoring\ServerChangedEvent</classname>
-    class encapsulates information about a changed server description.
+    class encapsulates information about a changed server description. For
+    example, a server's type changing from secondary to primary would cause its
+    server description to change.
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/mongodb/mongodb/driver/monitoring/serverclosedevent.xml b/reference/mongodb/mongodb/driver/monitoring/serverclosedevent.xml
index c8fcb7630a9a..36fb1d6698ee 100644
--- a/reference/mongodb/mongodb/driver/monitoring/serverclosedevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/serverclosedevent.xml
@@ -13,7 +13,8 @@
    &reftitle.intro;
    <para>
     The <classname>MongoDB\Driver\Monitoring\ServerClosedEvent</classname>
-    class encapsulates information about a closed server.
+    class encapsulates information about a closed server. This corresponds to an
+    existing server being removed from the topology.
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/mongodb/mongodb/driver/monitoring/serverheartbeatfailedevent.xml b/reference/mongodb/mongodb/driver/monitoring/serverheartbeatfailedevent.xml
index ca1d6ae75327..5bd93ea8c215 100644
--- a/reference/mongodb/mongodb/driver/monitoring/serverheartbeatfailedevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/serverheartbeatfailedevent.xml
@@ -13,7 +13,10 @@
    &reftitle.intro;
    <para>
     The <classname>MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent</classname>
-    class encapsulates information about a failed server heartbeat.
+    class encapsulates information about a failed server heartbeat (i.e.
+    <link xlink:href="&url.mongodb.docs;reference/command/hello/">hello</link>
+    command issued through
+    <link xlink:href="&url.mongodb.sdam;">server monitoring</link>).
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/mongodb/mongodb/driver/monitoring/serverheartbeatstartedevent.xml b/reference/mongodb/mongodb/driver/monitoring/serverheartbeatstartedevent.xml
index 89060400e272..b9eec2c03baf 100644
--- a/reference/mongodb/mongodb/driver/monitoring/serverheartbeatstartedevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/serverheartbeatstartedevent.xml
@@ -13,7 +13,10 @@
    &reftitle.intro;
    <para>
     The <classname>MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent</classname>
-    class encapsulates information about a started server heartbeat.
+    class encapsulates information about a started server heartbeat (i.e.
+    <link xlink:href="&url.mongodb.docs;reference/command/hello/">hello</link>
+    command issued through
+    <link xlink:href="&url.mongodb.sdam;">server monitoring</link>).
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/mongodb/mongodb/driver/monitoring/serverheartbeatsucceededevent.xml b/reference/mongodb/mongodb/driver/monitoring/serverheartbeatsucceededevent.xml
index e830e5c26222..d9b07cc59b9b 100644
--- a/reference/mongodb/mongodb/driver/monitoring/serverheartbeatsucceededevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/serverheartbeatsucceededevent.xml
@@ -13,7 +13,10 @@
    &reftitle.intro;
    <para>
     The <classname>MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent</classname>
-    class encapsulates information about a successful server heartbeat.
+    class encapsulates information about a successful server heartbeat (i.e.
+    <link xlink:href="&url.mongodb.docs;reference/command/hello/">hello</link>
+    command issued through
+    <link xlink:href="&url.mongodb.sdam;">server monitoring</link>).
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/mongodb/mongodb/driver/monitoring/serveropeningevent.xml b/reference/mongodb/mongodb/driver/monitoring/serveropeningevent.xml
index a7d5d96c93e5..c334906cca38 100644
--- a/reference/mongodb/mongodb/driver/monitoring/serveropeningevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/serveropeningevent.xml
@@ -13,7 +13,8 @@
    &reftitle.intro;
    <para>
     The <classname>MongoDB\Driver\Monitoring\ServerOpeningEvent</classname>
-    class encapsulates information about an opened server.
+    class encapsulates information about an opened server. This corresponds to a
+    new server being added to the topology.
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/mongodb/mongodb/driver/monitoring/topologychangedevent.xml b/reference/mongodb/mongodb/driver/monitoring/topologychangedevent.xml
index 8292025181b6..49c9d86c25ff 100644
--- a/reference/mongodb/mongodb/driver/monitoring/topologychangedevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/topologychangedevent.xml
@@ -13,7 +13,9 @@
    &reftitle.intro;
    <para>
     The <classname>MongoDB\Driver\Monitoring\TopologyChangedEvent</classname>
-    class encapsulates information about a changed topology description.
+    class encapsulates information about a changed topology description. For
+    example, a topology discovering a new replica set primary would cause its
+    topology description to change.
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/mongodb/mongodb/driver/monitoring/topologyclosedevent.xml b/reference/mongodb/mongodb/driver/monitoring/topologyclosedevent.xml
index f1661a5f5e12..540e9379c1e7 100644
--- a/reference/mongodb/mongodb/driver/monitoring/topologyclosedevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/topologyclosedevent.xml
@@ -15,6 +15,16 @@
     The <classname>MongoDB\Driver\Monitoring\TopologyClosedEvent</classname>
     class encapsulates information about a closed topology.
    </para>
+   <note>
+    <simpara>
+     Due to the driver's
+     <link linkend="mongodb.connection-handling">connection handling and persistence</link>
+     behavior, this event can only be observed when a
+     <classname>MongoDB\Driver\Manager</classname> is created with the
+     <literal>"disableClientPersistence"</literal> driver option and freed
+     before request shutdown (RSHUTDOWN).
+    </simpara>
+   </note>
   </section>
 <!-- }}} -->
 
diff --git a/reference/mongodb/mongodb/driver/monitoring/topologyopeningevent.xml b/reference/mongodb/mongodb/driver/monitoring/topologyopeningevent.xml
index 311c66d3018d..3a7a52d6100f 100644
--- a/reference/mongodb/mongodb/driver/monitoring/topologyopeningevent.xml
+++ b/reference/mongodb/mongodb/driver/monitoring/topologyopeningevent.xml
@@ -15,6 +15,15 @@
     The <classname>MongoDB\Driver\Monitoring\TopologyOpeningEvent</classname>
     class encapsulates information about an opened topology.
    </para>
+   <note>
+    <simpara>
+     Due to the driver's
+     <link linkend="mongodb.connection-handling">connection handling and persistence</link>
+     behavior, this event may not be observed if a
+     <classname>MongoDB\Driver\Manager</classname> uses a previously persisted
+     <link xlink:href="&url.mongodb.libmongoc;">libmongoc</link> client.
+    </simpara>
+   </note>
   </section>
 <!-- }}} -->