Port System.Net.Http docs for HttpRequestError and metrics additions (#…

…9305) * HTTP: docs for HttpRequestError and metrics additions * add namespace docs * Apply suggestions from code review * inheritdoc is stupid * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> * Fix invalid xref * missing <returns> --------- Co-authored-by: Carlos Sánchez López <[email protected]> Co-authored-by: Genevieve Warren <[email protected]>
dotnet · Sep 18, 2023 · ea6147b · ea6147b
1 parent eb9031c
commit ea6147b
Show file tree

Hide file tree

Showing 9 changed files with 68 additions and 53 deletions.
diff --git a/xml/System.Net.Http.Metrics/HttpMetricsEnrichmentContext.xml b/xml/System.Net.Http.Metrics/HttpMetricsEnrichmentContext.xml
@@ -24,8 +24,21 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Provides functionality for enriching the <c>http.client.request.duration</c> metric.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Enrichment is done on per-request basis by callbacks registered with <xref:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCallback(System.Net.Http.HttpRequestMessage,System.Action{System.Net.Http.Metrics.HttpMetricsEnrichmentContext})>.
+
+The callbacks are responsible for adding custom tags via <xref:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCustomTag(System.String,System.Object)> for which they can use the request, response, and error information exposed on the <xref:System.Net.Http.Metrics.HttpMetricsEnrichmentContext> instance.
+ 
+ > [!IMPORTANT]
+ > The <xref:System.Net.Http.Metrics.HttpMetricsEnrichmentContext> instance must not be used from outside of the enrichment callbacks.
+ 
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="AddCallback">
@@ -48,9 +61,9 @@
         <Parameter Name="callback" Type="System.Action&lt;System.Net.Http.Metrics.HttpMetricsEnrichmentContext&gt;" />
       </Parameters>
       <Docs>
-        <param name="request">To be added.</param>
-        <param name="callback">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="request">The <see cref="T:System.Net.Http.HttpRequestMessage" /> to apply enrichment to.</param>
+        <param name="callback">The callback responsible for adding custom tags via <see cref="M:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCustomTag(System.String,System.Object)" />.</param>
+        <summary>Adds a callback to register custom tags for the <c>http.client.request.duration</c> metric.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -81,10 +94,10 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <param name="name">To be added.</param>
-        <param name="value">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="name">The name of the tag.</param>
+        <param name="value">The value of the tag.</param>
+        <summary>Appends a custom tag to the list of tags to be recorded with the <c>http.client.request.duration</c> metric.</summary>
+        <remarks>This method must not be used from outside of the enrichment callbacks.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Exception">
@@ -113,9 +126,9 @@
         <ReturnType>System.Exception</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the exception that occurred, or <see langword="null" /> if there was no error.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Request">
@@ -134,9 +147,9 @@
         <ReturnType>System.Net.Http.HttpRequestMessage</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the <see cref="T:System.Net.Http.HttpRequestMessage" /> that has been sent.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Response">
@@ -165,9 +178,9 @@
         <ReturnType>System.Net.Http.HttpResponseMessage</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the <see cref="T:System.Net.Http.HttpRequestMessage" /> received from the server, or <see langword="null" /> if the request failed.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Net.Http/HttpClientHandler.xml b/xml/System.Net.Http/HttpClientHandler.xml
@@ -850,9 +850,9 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA
         <ReturnType>System.Diagnostics.Metrics.IMeterFactory</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets the <see cref="T:System.Diagnostics.Metrics.IMeterFactory" /> to create a custom <see cref="T:System.Diagnostics.Metrics.Meter" /> for the <see cref="T:System.Net.Http.HttpClientHandler" /> instance.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>When <see cref="P:System.Net.Http.HttpClientHandler.MeterFactory" /> is set to a non-<see langword="null" /> value, all metrics emitted by the <see cref="T:System.Net.Http.HttpClientHandler" /> instance will be recorded using the <see cref="T:System.Diagnostics.Metrics.Meter" /> provided by the <see cref="T:System.Diagnostics.Metrics.IMeterFactory" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="PreAuthenticate">

diff --git a/xml/System.Net.Http/HttpIOException.xml b/xml/System.Net.Http/HttpIOException.xml
@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>The exception that is thrown when an error occurs while reading the response.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -41,10 +41,10 @@
         <Parameter Name="innerException" Type="System.Exception" />
       </Parameters>
       <Docs>
-        <param name="httpRequestError">To be added.</param>
-        <param name="message">To be added.</param>
-        <param name="innerException">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="httpRequestError">The <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</param>
+        <param name="message">The message string describing the error.</param>
+        <param name="innerException">The exception that is the cause of the current exception.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Net.Http.HttpIOException" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -64,7 +64,7 @@
         <ReturnType>System.Net.Http.HttpRequestError</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>

diff --git a/xml/System.Net.Http/HttpMethod.xml b/xml/System.Net.Http/HttpMethod.xml
@@ -599,10 +599,10 @@
         <Parameter Name="method" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="net-8.0" />
       </Parameters>
       <Docs>
-        <param name="method">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="method">The method to parse.</param>
+        <summary>Parses the provided <paramref name="method" /> into an <see cref="T:System.Net.Http.HttpMethod" /> instance.</summary>
+        <returns>An <see cref="T:System.Net.Http.HttpMethod" /> instance for the provided <paramref name="method" />.</returns>
+        <remarks>This method may return a singleton instance for known methods; for example, it may return <see cref="P:System.Net.Http.HttpMethod.Get" /> if "GET" is specified. The parsing is performed in a case-insensitive manner, so it may also return <see cref="P:System.Net.Http.HttpMethod.Get" /> if "get" is specified. For unknown methods, a new <see cref="T:System.Net.Http.HttpMethod" /> instance is returned, with the same validation being performed as by the <see cref="M:System.Net.Http.HttpMethod.#ctor(System.String)" /> constructor.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Patch">

diff --git a/xml/System.Net.Http/HttpRequestError.xml b/xml/System.Net.Http/HttpRequestError.xml
@@ -13,7 +13,7 @@
     <BaseTypeName>System.Enum</BaseTypeName>
   </Base>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Defines error categories representing the reason for <see cref="T:System.Net.Http.HttpRequestException" /> or <see cref="T:System.Net.Http.HttpIOException" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -34,7 +34,7 @@
       </ReturnValue>
       <MemberValue>11</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The response exceeded a pre-configured limit such as <see cref="P:System.Net.Http.HttpClient.MaxResponseContentBufferSize" /> or <see cref="P:System.Net.Http.HttpClientHandler.MaxResponseHeadersLength" />.</summary>
       </Docs>
     </Member>
     <Member MemberName="ConnectionError">
@@ -54,7 +54,7 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>A transport-level failure occurred while connecting to the remote endpoint.</summary>
       </Docs>
     </Member>
     <Member MemberName="ExtendedConnectNotSupported">
@@ -74,7 +74,7 @@
       </ReturnValue>
       <MemberValue>5</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Extended CONNECT for WebSockets over HTTP/2 is not supported by the peer.</summary>
       </Docs>
     </Member>
     <Member MemberName="HttpProtocolError">
@@ -94,7 +94,7 @@
       </ReturnValue>
       <MemberValue>4</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>An HTTP/2 or HTTP/3 protocol error occurred.</summary>
       </Docs>
     </Member>
     <Member MemberName="InvalidResponse">
@@ -114,7 +114,7 @@
       </ReturnValue>
       <MemberValue>9</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>An invalid or malformed response has been received.</summary>
       </Docs>
     </Member>
     <Member MemberName="NameResolutionError">
@@ -134,7 +134,7 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The DNS name resolution failed.</summary>
       </Docs>
     </Member>
     <Member MemberName="ProxyTunnelError">
@@ -154,7 +154,7 @@
       </ReturnValue>
       <MemberValue>8</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>An error occurred while establishing a connection to the proxy tunnel.</summary>
       </Docs>
     </Member>
     <Member MemberName="ResponseEnded">
@@ -174,7 +174,7 @@
       </ReturnValue>
       <MemberValue>10</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The response ended prematurely.</summary>
       </Docs>
     </Member>
     <Member MemberName="SecureConnectionError">
@@ -194,7 +194,7 @@
       </ReturnValue>
       <MemberValue>3</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>An error occurred during the TLS handshake.</summary>
       </Docs>
     </Member>
     <Member MemberName="Unknown">
@@ -214,7 +214,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>A generic or unknown error occurred.</summary>
       </Docs>
     </Member>
     <Member MemberName="UserAuthenticationError">
@@ -234,7 +234,7 @@
       </ReturnValue>
       <MemberValue>7</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>The authentication failed.</summary>
       </Docs>
     </Member>
     <Member MemberName="VersionNegotiationError">
@@ -254,7 +254,7 @@
       </ReturnValue>
       <MemberValue>6</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Cannot negotiate the HTTP version requested.</summary>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Net.Http/HttpRequestException.xml b/xml/System.Net.Http/HttpRequestException.xml
@@ -222,11 +222,11 @@
         <Parameter Name="statusCode" Type="System.Nullable&lt;System.Net.HttpStatusCode&gt;" Index="3" FrameworkAlternate="net-8.0" />
       </Parameters>
       <Docs>
-        <param name="httpRequestError">To be added.</param>
-        <param name="message">To be added.</param>
-        <param name="inner">To be added.</param>
-        <param name="statusCode">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="httpRequestError">The <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" /> that caused the exception.</param>
+        <param name="message">A message that describes the current exception.</param>
+        <param name="inner">The inner exception.</param>
+        <param name="statusCode">The HTTP status code.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Net.Http.HttpRequestException" /> class with a specific message an inner exception, and an HTTP status code and an <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -249,7 +249,7 @@
         <ReturnType>System.Net.Http.HttpRequestError</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>

diff --git a/xml/System.Net.Http/HttpRequestOptions.xml b/xml/System.Net.Http/HttpRequestOptions.xml
@@ -845,10 +845,12 @@ This member is an explicit interface member implementation. It can be used only
         <Parameter Name="value" Type="System.Object" RefType="out" Index="1" FrameworkAlternate="net-8.0" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="value">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="key">The key to locate.</param>
+        <param name="value">When this method returns, contains the value associated with the specified key, if the key is found; otherwise, the default value for the type of the <paramref name="value" /> parameter. This parameter is passed uninitialized.</param>
+        <summary>Gets the value that is associated with the specified key.</summary>
+        <returns><see langword="true" /> if the <see cref="T:System.Net.Http.HttpRequestOptions"/> instance contains an element with the specified key; otherwise, <see langword="false" />.</returns>
+
+
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

diff --git a/xml/System.Net.Http/SocketsHttpHandler.xml b/xml/System.Net.Http/SocketsHttpHandler.xml
@@ -766,9 +766,9 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
         <ReturnType>System.Diagnostics.Metrics.IMeterFactory</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets the <see cref="T:System.Diagnostics.Metrics.IMeterFactory" /> to create a custom <see cref="T:System.Diagnostics.Metrics.Meter" /> for the <see cref="T:System.Net.Http.SocketsHttpHandler" /> instance.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>When <see cref="P:System.Net.Http.SocketsHttpHandler.MeterFactory" /> is set to a non-<see langword="null" /> value, all metrics emitted by the <see cref="T:System.Net.Http.SocketsHttpHandler" /> instance will be recorded using the <see cref="T:System.Diagnostics.Metrics.Meter" /> provided by the <see cref="T:System.Diagnostics.Metrics.IMeterFactory" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="PlaintextStreamFilter">

diff --git a/xml/ns-System.Net.Http.Metrics.xml b/xml/ns-System.Net.Http.Metrics.xml
@@ -1,6 +1,6 @@
 <Namespace Name="System.Net.Http.Metrics">
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Provides additional APIs for advanced metrics use-cases.</summary>
     <remarks>To be added.</remarks>
   </Docs>
 </Namespace>