Skip to content

Commit 3d7e35f

Browse files
jozkeemairaw
jozkee
authored and
mairaw
committed
Added documentation for new System.Net APIs released in 3.0 (dotnet#2663)
* Added documentation for new APIs released in 3.0 * Addressing PR comments. * Addressed more PR comments. * Update CookieCollection.xml * Update FileWebRequest.xml * Update IPEndPoint.xml * fixed cref
1 parent d685608 commit 3d7e35f

File tree

3 files changed

+155
-41
lines changed

3 files changed

+155
-41
lines changed

‎xml/System.Net/CookieCollection.xml

Lines changed: 49 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,7 @@
257257
</ReturnValue>
258258
<Parameters />
259259
<Docs>
260-
<summary>To be added.</summary>
260+
<summary>Removes all elements from the <see cref="T:System.Net.CookieCollection" /> object.</summary>
261261
<remarks>To be added.</remarks>
262262
</Docs>
263263
</Member>
@@ -291,10 +291,19 @@
291291
<Parameter Name="cookie" Type="System.Net.Cookie" Index="0" FrameworkAlternate="netcore-3.0" />
292292
</Parameters>
293293
<Docs>
294-
<param name="cookie">To be added.</param>
295-
<summary>To be added.</summary>
296-
<returns>To be added.</returns>
297-
<remarks>To be added.</remarks>
294+
<param name="cookie">The cookie to locate in the <see cref="T:System.Net.CookieCollection" />.</param>
295+
<summary>Determines whether the specified cookie is in the <see cref="T:System.Net.CookieCollection" />.</summary>
296+
<returns><see langword="true" /> if the specified cookie is found in the <see cref="T:System.Net.CookieCollection" />; otherwise, <see langword="false" />.</returns>
297+
<remarks>
298+
<format type="text/markdown"><![CDATA[
299+
300+
## Remarks
301+
The `cookie` is determined to be part of the collection if <xref:System.Net.Cookie.Name%2A>, <xref:System.Net.Cookie.Domain%2A> and <xref:System.Net.Cookie.Path%2A> match.
302+
The comparison for <xref:System.Net.Cookie.Name%2A> and <xref:System.Net.Cookie.Domain%2A> is case-insensitive.
303+
The comparison for <xref:System.Net.Cookie.Path%2A> is case-sensitive.
304+
305+
]]></format>
306+
</remarks>
298307
</Docs>
299308
</Member>
300309
<MemberGroup MemberName="CopyTo">
@@ -345,9 +354,9 @@
345354
<Parameter Name="index" Type="System.Int32" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-2.0;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0;netstandard-2.1" />
346355
</Parameters>
347356
<Docs>
348-
<param name="array">The target <see cref="T:System.Array" /> to which the <see cref="T:System.Net.CookieCollection" /> will be copied.</param>
349-
<param name="index">The zero-based index in the target <see cref="T:System.Array" /> where copying begins.</param>
350-
<summary>Copies the elements of a <see cref="T:System.Net.CookieCollection" /> to an instance of the <see cref="T:System.Array" /> class, starting at a particular index.</summary>
357+
<param name="array">The target array to which the <see cref="T:System.Net.CookieCollection" /> will be copied.</param>
358+
<param name="index">The zero-based index in the target array where copying begins.</param>
359+
<summary>Copies the elements of a <see cref="T:System.Net.CookieCollection" /> to the specified array, starting at a particular index.</summary>
351360
<remarks>
352361
<format type="text/markdown"><![CDATA[
353362
@@ -405,13 +414,13 @@
405414
</Parameters>
406415
<Docs>
407416
<param name="array">The target <see cref="T:System.Net.Cookie" /> array to which the <see cref="T:System.Net.CookieCollection" /> will be copied.</param>
408-
<param name="index">The zero-based index in the target <see cref="T:System.Array" /> where copying begins.</param>
417+
<param name="index">The zero-based index in the target array where copying begins.</param>
409418
<summary>Copies the elements of this <see cref="T:System.Net.CookieCollection" /> to a <see cref="T:System.Net.Cookie" /> array starting at the specified index of the target array.</summary>
410419
<remarks>
411420
<format type="text/markdown"><![CDATA[
412421
413422
## Remarks
414-
The <xref:System.Array>`array` parameter must be one-dimensional with zero-based indexing.
423+
The `array` parameter must be one-dimensional with zero-based indexing.
415424
416425
]]></format>
417426
</remarks>
@@ -515,7 +524,7 @@
515524
<Parameters />
516525
<Docs>
517526
<summary>Gets an enumerator that can iterate through a <see cref="T:System.Net.CookieCollection" />.</summary>
518-
<returns>An instance of an implementation of an <see cref="T:System.Collections.IEnumerator" /> interface that can iterate through a <see cref="T:System.Net.CookieCollection" />.</returns>
527+
<returns>An <see cref="T:System.Collections.IEnumerator" /> for this collection.</returns>
519528
<remarks>
520529
<format type="text/markdown"><![CDATA[
521530
@@ -778,10 +787,20 @@
778787
<Parameter Name="cookie" Type="System.Net.Cookie" Index="0" FrameworkAlternate="netcore-3.0" />
779788
</Parameters>
780789
<Docs>
781-
<param name="cookie">To be added.</param>
782-
<summary>To be added.</summary>
783-
<returns>To be added.</returns>
784-
<remarks>To be added.</remarks>
790+
<param name="cookie">The cookie to remove from the <see cref="T:System.Net.CookieCollection" />.</param>
791+
<summary>Removes the specified cookie from the <see cref="T:System.Net.CookieCollection" />.</summary>
792+
<returns><see langword="true" /> if <paramref name="cookie" /> was successfully removed from the <see cref="T:System.Net.CookieCollection" />; otherwise, <see langword="false" />. This method also returns <see langword="false" /> if item is not found in the original collection.</returns>
793+
<remarks>
794+
<format type="text/markdown"><![CDATA[
795+
796+
## Remarks
797+
The `cookie` is determined to be part of the collection if <xref:System.Net.Cookie.Name%2A>, <xref:System.Net.Cookie.Domain%2A> and <xref:System.Net.Cookie.Path%2A> match.
798+
799+
The comparison for <xref:System.Net.Cookie.Name%2A> and <xref:System.Net.Cookie.Domain%2A> is case-insensitive.
800+
801+
The comparison for <xref:System.Net.Cookie.Path%2A> is case-sensitive.
802+
]]></format>
803+
</remarks>
785804
</Docs>
786805
</Member>
787806
<Member MemberName="SyncRoot">
@@ -860,9 +879,20 @@
860879
</ReturnValue>
861880
<Parameters />
862881
<Docs>
863-
<summary>To be added.</summary>
864-
<returns>To be added.</returns>
865-
<remarks>To be added.</remarks>
882+
<summary>Gets an enumerator that can iterate through the <see cref="T:System.Net.CookieCollection" />.</summary>
883+
<returns>An <see cref="T:System.Collections.Generic.IEnumerator`1" /> for this collection.</returns>
884+
<remarks>
885+
<format type="text/markdown"><![CDATA[
886+
887+
## Remarks
888+
You should use an <xref:System.Collections.Generic.IEnumerator%601> only to read data in the collection. Enumerators cannot be used to modify the underlying collection. The enumerator does not have exclusive access to the collection.
889+
890+
When an enumerator is created, it takes a snapshot of the current state of the collection. If changes are made to the collection, such as adding, modifying, or deleting elements, this snapshot gets out of sync and the enumerator throws an <xref:System.InvalidOperationException>. Two enumerators created from the same collection at the same time can produce different snapshots of the collection.
891+
892+
This member is an explicit interface member implementation. It can be used only when the <xref:System.Net.CookieCollection> instance is cast to an <xref:System.Collections.Generic.IEnumerable%601> interface.
893+
894+
]]></format>
895+
</remarks>
866896
</Docs>
867897
</Member>
868898
<Member MemberName="System.Collections.ICollection.CopyTo">
@@ -974,4 +1004,4 @@
9741004
</Docs>
9751005
</Member>
9761006
</Members>
977-
</Type>
1007+
</Type>

‎xml/System.Net/FileWebRequest.xml

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -717,9 +717,26 @@
717717
</ReturnValue>
718718
<Parameters />
719719
<Docs>
720-
<summary>To be added.</summary>
721-
<returns>To be added.</returns>
722-
<remarks>To be added.</remarks>
720+
<summary>Returns a stream for writing data to the file system resource as an asynchronous operation.</summary>
721+
<returns>The task object representing the asynchronous operation.</returns>
722+
<remarks>
723+
<format type="text/markdown"><![CDATA[
724+
725+
## Remarks
726+
727+
> [!NOTE]
728+
> In the case of asynchronous requests, the client application is responsible for implementing its own time-out mechanism.
729+
730+
]]>
731+
</format>
732+
</remarks>
733+
<exception cref="T:System.InvalidOperationException">The stream is being used by a previous call to <see cref="M:System.Net.FileWebRequest.BeginGetRequestStream(System.AsyncCallback,System.Object)"/>.
734+
735+
-or-
736+
737+
The stream already received a response previous to your request.</exception>
738+
<exception cref="T:System.Net.ProtocolViolationException">The <see cref="P:System.Net.FileWebRequest.Method" /> property is GET or HEAD.</exception>
739+
<exception cref="T:System.Net.WebException">The <see cref="T:System.Net.FileWebRequest" /> was aborted.</exception>
723740
</Docs>
724741
</Member>
725742
<Member MemberName="GetResponse">
@@ -799,9 +816,21 @@
799816
</ReturnValue>
800817
<Parameters />
801818
<Docs>
802-
<summary>To be added.</summary>
803-
<returns>To be added.</returns>
804-
<remarks>To be added.</remarks>
819+
<summary>Returns a response to a file system request as an asynchronous operation.</summary>
820+
<returns>The task object representing the asynchronous operation.</returns>
821+
<remarks>
822+
<format type="text/markdown"><![CDATA[
823+
824+
## Remarks
825+
826+
> [!NOTE]
827+
> In the case of asynchronous requests, the client application is responsible for implementing its own time-out mechanism.
828+
829+
]]>
830+
</format>
831+
</remarks>
832+
<exception cref="T:System.InvalidOperationException">The stream is already in use by a previous call to <see cref="M:System.Net.FileWebRequest.BeginGetResponse(System.AsyncCallback,System.Object)" />.</exception>
833+
<exception cref="T:System.Net.WebException">The <see cref="M:System.Net.FileWebRequest" /> was aborted.</exception>
805834
</Docs>
806835
</Member>
807836
<Member MemberName="Headers">
@@ -1198,4 +1227,4 @@
11981227
</Docs>
11991228
</Member>
12001229
</Members>
1201-
</Type>
1230+
</Type>

‎xml/System.Net/IPEndPoint.xml

Lines changed: 70 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,32 @@
540540
</remarks>
541541
</Docs>
542542
</Member>
543+
<MemberGroup MemberName="Parse">
544+
<Docs>
545+
<summary>To be added.</summary>
546+
<remarks>
547+
<format type="text/markdown"><![CDATA[
548+
549+
## Remarks
550+
551+
The number of parts (each part is separated by a period) in `s` determines how the endpoint's IP address is constructed. A one-part address is stored directly in the network address. A two-part address, convenient for specifying a class A address, puts the leading part in the first byte and the trailing part in the right-most three bytes of the network address. A three-part address, convenient for specifying a class B address, puts the first part in the first byte, the second part in the second byte, and the final part in the right-most two bytes of the network address. For example:
552+
553+
|Number of parts and example `s`|IPv4 address for IPEndPoint.Address|Port|
554+
|-------------------------|--------------------------------|-------------------------|
555+
|1 -- "1"|0.0.0.1|0|
556+
|2 -- "20.2:80"|20.0.0.2|80|
557+
|2 -- "20.65535:23"|20.0.255.255|23|
558+
|3 -- "128.1.2:443"|128.1.0.2|443|
559+
560+
> [!IMPORTANT]
561+
> Note that this method accepts as valid a value that can be parsed as an <xref:System.Int64>, and then treats that <xref:System.Int64> as the long value of an IP address in network byte order, similar to the way that the IPAddress constructor does. This means that this method returns true if the Int64 is parsed successfully, even if it represents an address that's not a valid IP address. For example, if s is "1", this method returns true even though "1" (or 0.0.0.1) is not a valid IP address and you might expect this method to return false. Fixing this bug would break existing apps, so the current behavior will not be changed. Your code can avoid this behavior by ensuring that it only uses this method to parse IP addresses in dotted-decimal format.
562+
563+
Literal IPv6 addresses require to be enclosed in square brackets [] when passing an endpoint that specifies a port number; otherwise, square braces are not mandatory.
564+
565+
]]></format>
566+
</remarks>
567+
</Docs>
568+
</MemberGroup>
543569
<Member MemberName="Parse">
544570
<MemberSignature Language="C#" Value="public static System.Net.IPEndPoint Parse (ReadOnlySpan&lt;char&gt; s);" />
545571
<MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Net.IPEndPoint Parse(valuetype System.ReadOnlySpan`1&lt;char&gt; s) cil managed" />
@@ -568,10 +594,12 @@
568594
<Parameter Name="s" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
569595
</Parameters>
570596
<Docs>
571-
<param name="s">To be added.</param>
572-
<summary>To be added.</summary>
573-
<returns>To be added.</returns>
597+
<param name="s">A read-only span that contains an IP endpoint in dotted-quad notation or network byte order for IPv4 and in colon-hexadecimal notation for IPv6.</param>
598+
<summary>Converts an IP network endpoint (address and port) represented as a read-only span to an <see cref="T:System.Net.IPEndPoint" /> instance.</summary>
599+
<returns>The object representation of an IP network endpoint.</returns>
574600
<remarks>To be added.</remarks>
601+
<exception cref="T:System.ArgumentNullException"><paramref name="s" /> is <see langword="null" />.</exception>
602+
<exception cref="T:System.FormatException"><paramref name="s" /> is not a valid IP endpoint.</exception>
575603
</Docs>
576604
</Member>
577605
<Member MemberName="Parse">
@@ -602,10 +630,12 @@
602630
<Parameter Name="s" Type="System.String" Index="0" FrameworkAlternate="netcore-3.0" />
603631
</Parameters>
604632
<Docs>
605-
<param name="s">To be added.</param>
606-
<summary>To be added.</summary>
607-
<returns>To be added.</returns>
633+
<param name="s">A string that contains an IP endpoint in dotted-quad notation or network byte order for IPv4 and in colon-hexadecimal notation for IPv6.</param>
634+
<summary>Converts an IP network endpoint (address and port) represented as a string to an <see cref="T:System.Net.IPEndPoint" /> instance.</summary>
635+
<returns>The object representation of an IP network endpoint.</returns>
608636
<remarks>To be added.</remarks>
637+
<exception cref="T:System.ArgumentNullException"><paramref name="s" /> is <see langword="null" />.</exception>
638+
<exception cref="T:System.FormatException"><paramref name="s" /> is not a valid IP endpoint.</exception>
609639
</Docs>
610640
</Member>
611641
<Member MemberName="Port">
@@ -764,6 +794,31 @@
764794
</remarks>
765795
</Docs>
766796
</Member>
797+
<MemberGroup MemberName="TryParse">
798+
<Docs>
799+
<summary>To be added.</summary>
800+
<remarks>
801+
<format type="text/markdown"><![CDATA[
802+
803+
## Remarks
804+
The number of parts (each part is separated by a period) in `s` determines how the endpoint's IP address is constructed. A one-part address is stored directly in the network address. A two-part address, convenient for specifying a class A address, puts the leading part in the first byte and the trailing part in the right-most three bytes of the network address. A three-part address, convenient for specifying a class B address, puts the first part in the first byte, the second part in the second byte, and the final part in the right-most two bytes of the network address. For example:
805+
806+
|Number of parts and example `s`|IPv4 address for IPEndPoint.Address|Port|
807+
|-------------------------|--------------------------------|-------------------------|
808+
|1 -- "1"|0.0.0.1|0|
809+
|2 -- "20.2:80"|20.0.0.2|80|
810+
|2 -- "20.65535:23"|20.0.255.255|23|
811+
|3 -- "128.1.2:443"|128.1.0.2|443|
812+
813+
> [!IMPORTANT]
814+
> Note that this method accepts as valid a value that can be parsed as an <xref:System.Int64>, and then treats that <xref:System.Int64> as the long value of an IP address in network byte order, similar to the way that the IPAddress constructor does. This means that this method returns true if the Int64 is parsed successfully, even if it represents an address that's not a valid IP address. For example, if s is "1", this method returns true even though "1" (or 0.0.0.1) is not a valid IP address and you might expect this method to return false. Fixing this bug would break existing apps, so the current behavior will not be changed. Your code can avoid this behavior by ensuring that it only uses this method to parse IP addresses in dotted-decimal format.
815+
816+
Literal IPv6 addresses require to be enclosed in square brackets [] when passing an endpoint that specifies a port number; otherwise, square braces are not mandatory.
817+
818+
]]></format>
819+
</remarks>
820+
</Docs>
821+
</MemberGroup>
767822
<Member MemberName="TryParse">
768823
<MemberSignature Language="C#" Value="public static bool TryParse (ReadOnlySpan&lt;char&gt; s, out System.Net.IPEndPoint result);" />
769824
<MemberSignature Language="ILAsm" Value=".method public static hidebysig bool TryParse(valuetype System.ReadOnlySpan`1&lt;char&gt; s, [out] class System.Net.IPEndPoint&amp; result) cil managed" />
@@ -793,10 +848,10 @@
793848
<Parameter Name="result" Type="System.Net.IPEndPoint" RefType="out" Index="1" FrameworkAlternate="netcore-3.0" />
794849
</Parameters>
795850
<Docs>
796-
<param name="s">To be added.</param>
797-
<param name="result">To be added.</param>
798-
<summary>To be added.</summary>
799-
<returns>To be added.</returns>
851+
<param name="s">The IP endpoint to validate.</param>
852+
<param name="result">When this method returns, the <see cref="T:System.Net.IPEndPoint" /> version of <paramref name="s" />.</param>
853+
<summary>Tries to convert an IP network endpoint (address and port) represented as a read-only span to its <see cref="T:System.Net.IPEndPoint" /> equivalent, and returns a value that indicates whether the conversion succeeded.</summary>
854+
<returns><see langword="true" /> if <paramref name="s" /> can be parsed as an IP endpoint; otherwise, <see langword="false" />.</returns>
800855
<remarks>To be added.</remarks>
801856
</Docs>
802857
</Member>
@@ -829,12 +884,12 @@
829884
<Parameter Name="result" Type="System.Net.IPEndPoint" RefType="out" Index="1" FrameworkAlternate="netcore-3.0" />
830885
</Parameters>
831886
<Docs>
832-
<param name="s">To be added.</param>
833-
<param name="result">To be added.</param>
834-
<summary>To be added.</summary>
835-
<returns>To be added.</returns>
887+
<param name="s">The IP endpoint to validate.</param>
888+
<param name="result">When this method returns, the <see cref="T:System.Net.IPEndPoint" /> version of <paramref name="s" />.</param>
889+
<summary>Tries to convert an IP network endpoint (address and port) represented as a string to its <see cref="T:System.Net.IPEndPoint" /> equivalent, and returns a value that indicates whether the conversion succeeded.</summary>
890+
<returns><see langword="true" /> if <paramref name="s" /> can be parsed as an IP endpoint; otherwise, <see langword="false" />.</returns>
836891
<remarks>To be added.</remarks>
837892
</Docs>
838893
</Member>
839894
</Members>
840-
</Type>
895+
</Type>

0 commit comments

Comments
 (0)