standardize exception wording (dotnet#7630)

Author: gewarren

xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml

@@ -15,7 +15,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>The <see cref="T:System.DirectoryServices.Protocols.DsmlSoapConnection" /> class is an abstract class that cannot be instantiated. It enables stateless and stateful protocols to be handled similarly by providing session-oriented features.</summary>
+    <summary>An abstract class that cannot be instantiated. It enables stateless and stateful protocols to be handled similarly by providing session-oriented features.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -33,7 +33,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>The <see cref="M:System.DirectoryServices.Protocols.DsmlSoapConnection.#ctor" /> constructor initializes a new instance of a <see cref="T:System.DirectoryServices.Protocols.DsmlSoapConnection" /> class.</summary>
+        <summary>Initializes a new instance of a <see cref="T:System.DirectoryServices.Protocols.DsmlSoapConnection" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -55,7 +55,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>The <see cref="M:System.DirectoryServices.Protocols.DsmlSoapConnection.BeginSession" /> method instructs the DSML server to start a new session.</summary>
+        <summary>Instructs the DSML server to start a new session.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
@@ -64,9 +64,9 @@
   
  ]]></format>
         </remarks>
-        <exception cref="T:System.InvalidOperationException">Thrown when a session is already open on the connection.</exception>
-        <exception cref="T:System.DirectoryServices.Protocols.DsmlInvalidDocumentException">Thrown when the XML returned from the Server in response to the BeginSession is not well-formed.</exception>
-        <exception cref="T:System.Net.WebException">Thrown when there is a communications failure with the DSML server.</exception>
+        <exception cref="T:System.InvalidOperationException">A session is already open on the connection.</exception>
+        <exception cref="T:System.DirectoryServices.Protocols.DsmlInvalidDocumentException">The XML returned from the Server in response to the BeginSession is not well-formed.</exception>
+        <exception cref="T:System.Net.WebException">There is a communications failure with the DSML server.</exception>
       </Docs>
     </Member>
     <Member MemberName="EndSession">
@@ -87,21 +87,19 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>The <see cref="M:System.DirectoryServices.Protocols.DsmlSoapConnection.EndSession" /> method ends the session with the DSML server and clears the <see cref="P:System.DirectoryServices.Protocols.DsmlSoapConnection.SessionId" /> property.</summary>
+        <summary>Ends the session with the DSML server and clears the <see cref="P:System.DirectoryServices.Protocols.DsmlSoapConnection.SessionId" /> property.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
  The method will block while waiting for a response from the DSML server and will timeout according to the <xref:System.DirectoryServices.Protocols.DirectoryConnection.Timeout%2A> property.  
   
- If the DSML server terminates the session, a <xref:System.Net.WebException>  
-  
- is thrown. If <xref:System.DirectoryServices.Protocols.DsmlSoapConnection.SessionId%2A> is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid.  
+ If the DSML server terminates the session, a <xref:System.Net.WebException> is thrown. If <xref:System.DirectoryServices.Protocols.DsmlSoapConnection.SessionId%2A> is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid.  
   
  ]]></format>
         </remarks>
-        <exception cref="T:System.Net.WebException">Thrown when a communications failure occurs with the DSML server.</exception>
-        <exception cref="T:System.InvalidOperationException">Thrown when there is no open session.</exception>
+        <exception cref="T:System.Net.WebException">A communications failure occurred with the DSML server.</exception>
+        <exception cref="T:System.InvalidOperationException">There is no open session.</exception>
       </Docs>
     </Member>
     <Member MemberName="SessionId">
@@ -121,16 +119,9 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The <see cref="P:System.DirectoryServices.Protocols.DsmlSoapConnection.SessionId" /> property contains the active session ID.</summary>
-        <value>The active session ID.</value>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- A null value signifies no active session.  
-  
- ]]></format>
-        </remarks>
+        <summary>Gets the active session ID.</summary>
+        <value>The active session ID, or <see langword="null" /> if there is no active session.</value>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="SoapRequestHeader">
@@ -150,15 +141,17 @@
         <ReturnType>System.Xml.XmlNode</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The <see cref="P:System.DirectoryServices.Protocols.DsmlSoapConnection.SoapRequestHeader" /> property contains the SOAP Header attached to outgoing requests.</summary>
+        <summary>Gets or sets the SOAP Header attached to outgoing requests.</summary>
         <value>The SOAP Header attached to outgoing requests.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
-## Remarks  
- The API uses <xref:System.DirectoryServices.Protocols.DsmlSoapConnection.BeginSession%2A> and <xref:System.DirectoryServices.Protocols.DsmlSoapConnection.EndSession%2A> to track the lifetime of a session.  
+## Remarks
+
+The API uses <xref:System.DirectoryServices.Protocols.DsmlSoapConnection.BeginSession%2A> and <xref:System.DirectoryServices.Protocols.DsmlSoapConnection.EndSession%2A> to track the lifetime of a session.  
   
- **Caution** Attaching an EndSession header to the <xref:System.DirectoryServices.Protocols.DsmlSoapConnection.SoapRequestHeader%2A> causes the API to become inconsistent with the connection and should be avoided.  
+> [!CAUTION]
+> Attaching an `EndSession` header to the <xref:System.DirectoryServices.Protocols.DsmlSoapConnection.SoapRequestHeader%2A> causes the API to become inconsistent with the connection and should be avoided.  
   
  ]]></format>
         </remarks>