Improve docs for when SDAM Monitoring events are dispatched

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>
 

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>
 

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>
 

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>
 

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">

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">

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>
 <!-- }}} -->

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>
 <!-- }}} -->

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>
 <!-- }}} -->

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>
 <!-- }}} -->

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>
 <!-- }}} -->

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>
 <!-- }}} -->

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>
 <!-- }}} -->

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>
 <!-- }}} -->
 

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>
 <!-- }}} -->