Added documentation for new System.Net APIs released in 3.0 #2663
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -540,6 +540,32 @@ | |
| </remarks> | ||
| </Docs> | ||
| </Member> | ||
| <MemberGroup MemberName="Parse"> | ||
| <Docs> | ||
| <summary>To be added.</summary> | ||
| <remarks> | ||
| <format type="text/markdown"><![CDATA[ | ||
|
|
||
| ## Remarks | ||
|
|
||
| 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: | ||
|
|
||
| |Number of parts and example `s`|IPv4 address for IPEndPoint.Address|Port| | ||
| |-------------------------|--------------------------------|-------------------------| | ||
| |1 -- "1"|0.0.0.1|0| | ||
| |2 -- "20.2:80"|20.0.0.2|80| | ||
| |2 -- "20.65535:23"|20.0.255.255|23| | ||
| |3 -- "128.1.2:443"|128.1.0.2|443| | ||
|
|
||
| > [!IMPORTANT] | ||
| > 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. | ||
|
|
||
| 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. | ||
|
|
||
| ]]></format> | ||
| </remarks> | ||
| </Docs> | ||
| </MemberGroup> | ||
| <Member MemberName="Parse"> | ||
| <MemberSignature Language="C#" Value="public static System.Net.IPEndPoint Parse (ReadOnlySpan<char> s);" /> | ||
| <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Net.IPEndPoint Parse(valuetype System.ReadOnlySpan`1<char> s) cil managed" /> | ||
|
|
@@ -568,10 +594,12 @@ | |
| <Parameter Name="s" Type="System.ReadOnlySpan<System.Char>" Index="0" FrameworkAlternate="netcore-3.0" /> | ||
| </Parameters> | ||
| <Docs> | ||
| <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> | ||
| <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> | ||
| <returns>The object representation of an IP network endpoint.</returns> | ||
| <remarks>To be added.</remarks> | ||
|
Member
Author
There was a problem hiding this comment. Since overloads are generated in the same html, for this case and
Contributor
There was a problem hiding this comment. Yes, that's good. But if they are applicable to both, the best would be to create a MemberGroup element and add the remarks there. Here's an example I did this for: Otherwise, only one of the overloads have those remarks: I can help you to format that in this PR if you'd like. |
||
| <exception cref="T:System.ArgumentNullException"><paramref name="s" /> is <see langword="null" />.</exception> | ||
| <exception cref="T:System.FormatException"><paramref name="s" /> is not a valid IP endpoint.</exception> | ||
| </Docs> | ||
| </Member> | ||
| <Member MemberName="Parse"> | ||
|
|
@@ -602,10 +630,12 @@ | |
| <Parameter Name="s" Type="System.String" Index="0" FrameworkAlternate="netcore-3.0" /> | ||
| </Parameters> | ||
| <Docs> | ||
| <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> | ||
| <summary>Converts an IP network endpoint (address and port) represented as a string to an <see cref="T:System.Net.IPEndPoint" /> instance.</summary> | ||
| <returns>The object representation of an IP network endpoint.</returns> | ||
| <remarks>To be added.</remarks> | ||
| <exception cref="T:System.ArgumentNullException"><paramref name="s" /> is <see langword="null" />.</exception> | ||
| <exception cref="T:System.FormatException"><paramref name="s" /> is not a valid IP endpoint.</exception> | ||
| </Docs> | ||
| </Member> | ||
| <Member MemberName="Port"> | ||
|
|
@@ -764,6 +794,31 @@ | |
| </remarks> | ||
| </Docs> | ||
| </Member> | ||
| <MemberGroup MemberName="TryParse"> | ||
| <Docs> | ||
| <summary>To be added.</summary> | ||
| <remarks> | ||
| <format type="text/markdown"><![CDATA[ | ||
|
|
||
| ## Remarks | ||
| 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: | ||
|
|
||
| |Number of parts and example `s`|IPv4 address for IPEndPoint.Address|Port| | ||
| |-------------------------|--------------------------------|-------------------------| | ||
| |1 -- "1"|0.0.0.1|0| | ||
| |2 -- "20.2:80"|20.0.0.2|80| | ||
| |2 -- "20.65535:23"|20.0.255.255|23| | ||
| |3 -- "128.1.2:443"|128.1.0.2|443| | ||
|
|
||
| > [!IMPORTANT] | ||
| > 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. | ||
|
|
||
| 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. | ||
|
|
||
| ]]></format> | ||
| </remarks> | ||
| </Docs> | ||
| </MemberGroup> | ||
| <Member MemberName="TryParse"> | ||
| <MemberSignature Language="C#" Value="public static bool TryParse (ReadOnlySpan<char> s, out System.Net.IPEndPoint result);" /> | ||
| <MemberSignature Language="ILAsm" Value=".method public static hidebysig bool TryParse(valuetype System.ReadOnlySpan`1<char> s, [out] class System.Net.IPEndPoint& result) cil managed" /> | ||
|
|
@@ -793,10 +848,10 @@ | |
| <Parameter Name="result" Type="System.Net.IPEndPoint" RefType="out" Index="1" FrameworkAlternate="netcore-3.0" /> | ||
| </Parameters> | ||
| <Docs> | ||
| <param name="s">The IP endpoint to validate.</param> | ||
| <param name="result">When this method returns, the <see cref="T:System.Net.IPEndPoint" /> version of <paramref name="s" />.</param> | ||
| <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> | ||
| <returns><see langword="true" /> if <paramref name="s" /> can be parsed as an IP endpoint; otherwise, <see langword="false" />.</returns> | ||
| <remarks>To be added.</remarks> | ||
| </Docs> | ||
| </Member> | ||
|
|
@@ -829,12 +884,12 @@ | |
| <Parameter Name="result" Type="System.Net.IPEndPoint" RefType="out" Index="1" FrameworkAlternate="netcore-3.0" /> | ||
| </Parameters> | ||
| <Docs> | ||
| <param name="s">The IP endpoint to validate.</param> | ||
| <param name="result">When this method returns, the <see cref="T:System.Net.IPEndPoint" /> version of <paramref name="s" />.</param> | ||
| <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> | ||
| <returns><see langword="true" /> if <paramref name="s" /> can be parsed as an IP endpoint; otherwise, <see langword="false" />.</returns> | ||
| <remarks>To be added.</remarks> | ||
| </Docs> | ||
| </Member> | ||
| </Members> | ||
| </Type> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.