Added documentation for System.Net.Http properties targeted for 3.0 (#2733)

* Added documentation for System.Net.Http properties

* Addressed PR comments.
Reworded  DefaultProxy platform-specific configuration.

* Apply suggestions from code review

* Applying lexical suggestions.
* replaced OSX for macOS and Unix for Linux.

Co-Authored-By: Ron Petrusha <[email protected]>

Author: jozkee

xml/System.Net.Http/HttpClient.xml

@@ -368,9 +368,32 @@ The specified `handler` will be disposed of by calling [HttpClient.Dispose](xref
         <ReturnType>System.Net.IWebProxy</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets or sets the global Http proxy.</summary>
+        <value>A proxy used by every call that instantiates a <see cref="T:System.Net.HttpWebRequest" />.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks
+This static property determines the default proxy that all <xref:System.Net.Http.HttpClient> instances use if no proxy is set explicitly in the <xref:System.Net.Http.HttpClientHandler> passed through its constructor. 
+
+The default instance returned by this property will initialize following a different set of rules depending on your platform:
+* **For Windows:** Reads proxy configuration from environment variables or, if those are not defined, from the user's proxy settings.
+
+* **For macOS:** Reads proxy configuration from environment variables or, if those are not defined, from the system's proxy settings.
+
+* **For Linux:** Reads proxy configuration from environment variables or, in case those are not defined, this property initializes a non-configured instance that bypasses all addresses.
+
+The environment variables used for `DefaultProxy` initialization on Windows and Unix-based platforms are:
+* HTTP_PROXY: the hostname or IP address of the proxy server used on HTTP requests.
+* HTTPS_PROXY: the hostname or IP address of the proxy server used on HTTPS requests.
+* ALL_PROXY: the hostname or IP address of the proxy server used on HTTP and/or HTTPS requests in case HTTP_PROXY and/or HTTPS_PROXY are not defined.
+* NO_PROXY: a comma-separated list of hostnames that should be excluded from proxying.
+
+ ]]></format>
+      </remarks>
+      <exception cref="T:System.ArgumentNullException">
+          The value passed cannot be <see langword="null" />.
+      </exception>
       </Docs>
     </Member>
     <Member MemberName="DefaultRequestHeaders">
@@ -429,10 +452,23 @@ The specified `handler` will be disposed of by calling [HttpClient.Dispose](xref
         <ReturnType>System.Version</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
-      </Docs>
+        <summary>Gets or sets the default HTTP version used on subsequent requests made by this <see cref="T:System.Net.Http.HttpClient" /> instance.</summary>
+        <value>The default version to use for any requests made with this <see cref="T:System.Net.Http.HttpClient" /> instance.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+`DefaultRequestVersion` is <xref:System.Net.HttpVersion.Version11?displayProperty=nameWithType> by default.
+
+The `DefaultRequestVersion` property specifies the default HTTP version to use for any requests sent using this <xref:System.Net.Http.HttpClient> instance, such as calls to <xref:System.Net.Http.HttpClient.GetAsync%2A>, <xref:System.Net.Http.HttpClient.GetStringAsync%2A>, or <xref:System.Net.Http.HttpClient.SendAsync%2A>.
+
+The `DefaultRequestVersion` property can be changed as long as the <xref:System.Net.Http.HttpClient> instance has not started any request.
+ ]]></format>
+      </remarks>
+      <exception cref="T:System.ArgumentNullException">In a set operation, <see langword="DefaultRequestVersion" /> is <see langword="null" />.</exception>
+      <exception cref="T:System.InvalidOperationException">The <see cref="T:System.Net.Http.HttpClient" /> instance has already started one or more requests.</exception>
+      <exception cref="T:System.ObjectDisposedException">The <see cref="T:System.Net.Http.HttpClient" /> instance has already been disposed.</exception>
+    </Docs>
     </Member>
     <MemberGroup MemberName="DeleteAsync">
       <AssemblyInfo>
@@ -2244,4 +2280,4 @@ httpClient.Timeout = TimeSpan.FromMinutes(10);
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Net.Http/HttpResponseMessage.xml

@@ -484,9 +484,21 @@
         <ReturnType>System.Net.Http.Headers.HttpResponseHeaders</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets the collection of trailing headers included in an HTTP response.</summary>
+        <value>The collection of trailing headers in the HTTP response.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+Forbidden headers will be ignored.
+
+Since trailing headers are sent as an HTTP header appended at the end of the response message, the `TrailingHeaders` property returns an empty <xref:System.Net.Http.Headers.HttpResponseHeaders> instance if it is accessed and the response content has not been read completely. 
+
+For additional information on trailing headers, see [RFC 7230 - 4.1.2. Chunked Trailer Part](https://tools.ietf.org/html/rfc7230#section-4.1.2).
+
+ ]]></format>
+        </remarks>
+        <exception cref="T:System.Net.Http.HttpRequestException">PROTOCOL_ERROR: The HTTP/2 response contains pseudo-headers in the Trailing Headers Frame.</exception>
       </Docs>
     </Member>
     <Member MemberName="Version">
@@ -520,4 +532,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>