Skip to content

Commit aee70ed

Browse files
Jan JahodaJan Jahodacarlossanlop
authored
Add PhysicalAddress Parse methods documentation (#4750)
* Add PhysicalAddress parse methods documentation * Apply suggestions from code review Co-authored-by: Carlos Sanchez <[email protected]> Co-authored-by: Jan Jahoda <[email protected]> Co-authored-by: Carlos Sanchez <[email protected]>
1 parent 3e9efd4 commit aee70ed

File tree

3 files changed

+100
-16
lines changed

3 files changed

+100
-16
lines changed

‎samples/snippets/csharp/VS_Snippets_Remoting/NCLPhysicalAddress/CS/NCLPhysicalAddress.csproj

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net5.0</TargetFramework>
6+
</PropertyGroup>
7+
8+
</Project>

‎samples/snippets/csharp/VS_Snippets_Remoting/NCLPhysicalAddress/CS/physaddresstester.cs

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,17 @@ public static PhysicalAddress StrictParseAddress(string address)
106106
}
107107
//</snippet5>
108108

109+
//<snippet6>
110+
public static PhysicalAddress StrictParseAddress(ReadOnlySpan<char> address)
111+
{
112+
PhysicalAddress newAddress = PhysicalAddress.Parse(address);
113+
if (PhysicalAddress.None.Equals(newAddress))
114+
return null;
115+
116+
return newAddress;
117+
}
118+
//</snippet6>
119+
109120
public static void Main()
110121
{
111122
DisplayAddressNone();
@@ -117,8 +128,11 @@ public static void Main()
117128
Console.WriteLine(address.ToString());
118129
}
119130

120-
PhysicalAddress a = StrictParseAddress(null);
121-
Console.WriteLine(a== null? "null" : a.ToString());
131+
PhysicalAddress a = StrictParseAddress((string)null);
132+
Console.WriteLine(a?.ToString() ?? "null");
133+
134+
PhysicalAddress b = StrictParseAddress("".AsSpan());
135+
Console.WriteLine(b?.ToString() ?? "null");
122136
}
123137
}
124138
}

‎xml/System.Net.NetworkInformation/PhysicalAddress.xml

Lines changed: 76 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -313,10 +313,36 @@
313313
<Parameter Name="address" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="net-5.0" />
314314
</Parameters>
315315
<Docs>
316-
<param name="address">To be added.</param>
317-
<summary>To be added.</summary>
318-
<returns>To be added.</returns>
319-
<remarks>To be added.</remarks>
316+
<param name="address">A span containing the address that will be used to initialize the <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> instance returned by this method.</param>
317+
<summary>Parses the specified span and stores its contents as the address bytes of the <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> returned by this method.</summary>
318+
<returns>A <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> instance with the specified address.</returns>
319+
<remarks>
320+
<format type="text/markdown"><![CDATA[
321+
322+
## Remarks
323+
The `address` parameter must contain a string that can only consist of numbers and upper-case letters as hexadecimal digits. Some examples of string formats that are acceptable are as follows:
324+
325+
`001122334455`
326+
327+
`00-11-22-33-44-55`
328+
329+
`F0-E1-D2-C3-B4-A5`
330+
331+
Note that an address that contains `f0-e1-d2-c3-b4-a5` will fail to parse and throw an exception.
332+
333+
Use the <xref:System.Net.NetworkInformation.PhysicalAddress.GetAddressBytes%2A> method to retrieve the address from an existing <xref:System.Net.NetworkInformation.PhysicalAddress> instance.
334+
335+
336+
337+
## Examples
338+
The following code example creates a <xref:System.Net.NetworkInformation.PhysicalAddress> instance by calling the <xref:System.Net.NetworkInformation.PhysicalAddress.Parse%2A> method.
339+
340+
[!code-csharp[NCLPhysicalAddress#5](~/samples/snippets/csharp/VS_Snippets_Remoting/NCLPhysicalAddress/CS/physaddresstester.cs#6)]
341+
342+
]]></format>
343+
</remarks>
344+
<exception cref="T:System.FormatException">
345+
<paramref name="address" /> contains an illegal hardware address or contains a string in the incorrect format.</exception>
320346
</Docs>
321347
</Member>
322348
<Member MemberName="Parse">
@@ -464,11 +490,29 @@
464490
</Parameter>
465491
</Parameters>
466492
<Docs>
467-
<param name="address">To be added.</param>
468-
<param name="value">To be added.</param>
469-
<summary>To be added.</summary>
470-
<returns>To be added.</returns>
471-
<remarks>To be added.</remarks>
493+
<param name="address">A span containing the address that will be used to initialize the <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> instance returned by this method.</param>
494+
<param name="value">When this method returns, contains the <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> instance equivalent of the address contained in <paramref name="address" />, if the conversion succeeded, or <see langword="null" /> if the conversion failed. This parameter is passed uninitialized; any value originally supplied in <paramref name="result" /> will be overwritten.</param>
495+
<summary>Tries to convert the span representation of a hardware address to a <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> instance. A return value indicates whether the conversion succeeded.</summary>
496+
<returns>
497+
<see langword="true" /> if <paramref name="address" /> was converted successfully; otherwise, <see langword="false" />.</returns>
498+
<remarks>
499+
<format type="text/markdown"><![CDATA[
500+
501+
## Remarks
502+
The `address` parameter must contain a string that can only consist of numbers and upper-case letters as hexadecimal digits. Some examples of string formats that are legal are as follows:
503+
504+
`001122334455`
505+
506+
`00-11-22-33-44-55`
507+
508+
`F0-E1-D2-C3-B4-A5`
509+
510+
Note that an address that contains `f0-e1-d2-c3-b4-a5` is illegal.
511+
512+
Use the <xref:System.Net.NetworkInformation.PhysicalAddress.GetAddressBytes%2A> method to retrieve the address from an existing <xref:System.Net.NetworkInformation.PhysicalAddress> instance.
513+
514+
]]></format>
515+
</remarks>
472516
</Docs>
473517
</Member>
474518
<Member MemberName="TryParse">
@@ -501,11 +545,29 @@
501545
</Parameter>
502546
</Parameters>
503547
<Docs>
504-
<param name="address">To be added.</param>
505-
<param name="value">To be added.</param>
506-
<summary>To be added.</summary>
507-
<returns>To be added.</returns>
508-
<remarks>To be added.</remarks>
548+
<param name="address">A string containing the address that will be used to initialize the <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> instance returned by this method.</param>
549+
<param name="value">When this method returns, contains the <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> instance equivalent of the address contained in <paramref name="address" />, if the conversion succeeded, or <see langword="null" /> if the conversion failed. If the <paramref name="address" /> is <see langword="null" /> it contains <see cref="T:System.Net.NetworkInformation.PhysicalAddress.None" />. This parameter is passed uninitialized; any value originally supplied in <paramref name="result" /> will be overwritten.</param>
550+
<summary>Tries to convert the string representation of a hardware address to a <see cref="T:System.Net.NetworkInformation.PhysicalAddress" /> instance. A return value indicates whether the conversion succeeded.</summary>
551+
<returns>
552+
<see langword="true" /> if <paramref name="address" /> was converted successfully; otherwise, <see langword="false" />.</returns>
553+
<remarks>
554+
<format type="text/markdown"><![CDATA[
555+
556+
## Remarks
557+
The `address` parameter must contain a string that can only consist of numbers and upper-case letters as hexadecimal digits. Some examples of string formats that are legal are as follows:
558+
559+
`001122334455`
560+
561+
`00-11-22-33-44-55`
562+
563+
`F0-E1-D2-C3-B4-A5`
564+
565+
Note that an address that contains `f0-e1-d2-c3-b4-a5` is illegal.
566+
567+
Use the <xref:System.Net.NetworkInformation.PhysicalAddress.GetAddressBytes%2A> method to retrieve the address from an existing <xref:System.Net.NetworkInformation.PhysicalAddress> instance.
568+
569+
]]></format>
570+
</remarks>
509571
</Docs>
510572
</Member>
511573
</Members>

0 commit comments

Comments
 (0)