Skip to content

Commit

Permalink
Fix documentation (#302)
Browse files Browse the repository at this point in the history 
* Fix: documentations

* Fix: documentation

---------

Co-authored-by: lduchosal <[email protected]>
  • Loading branch information
@lduchosal
lduchosal and lduchosal authored Jan 18, 2024
1 parent 9088d92 commit 137a12e
Show file tree
Hide file tree
Showing 3 changed files with 190 additions and 13 deletions.
32 changes: 31 additions & 1 deletion src/System.Net.IPNetwork/IPAddressCollection.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,23 @@ namespace System.Net
using System.Collections.Generic;
using System.Numerics;

/// <summary>
/// Represents different filters for a collection of items.
/// </summary>
public enum FilterEnum
{
/// <summary>
/// Every IPAdresses are returned
/// </summary>
All,
/// <summary>
/// Returns only usable IPAdresses
/// </summary>
Usable,
}

/// <summary>
/// A collection of IP Adresses
/// Represents a collection of IP addresses within a specific IP network.
/// </summary>
public class IPAddressCollection : IEnumerable<IPAddress>, IEnumerator<IPAddress>
{
Expand All @@ -31,6 +40,13 @@ internal IPAddressCollection(IPNetwork2 ipnetwork, FilterEnum filter)
}

#region Count, Array, Enumerator

/// <summary>
/// Gets the count of IP addresses within the network.
/// </summary>
/// <value>
/// The count of IP addresses within the network.
/// </value>
public BigInteger Count
{
get
Expand All @@ -50,6 +66,12 @@ public BigInteger Count
}
}

/// <summary>
/// Gets the IP address corresponding to the given index from the IPNetwork collection.
/// </summary>
/// <param name="i">The index of the IP address to retrieve.</param>
/// <returns>The IP address corresponding to the given index.</returns>
/// <exception cref="ArgumentOutOfRangeException">Thrown when the given index is greater than or equal to the Count property of the IPNetwork collection.</exception>
public IPAddress this[BigInteger i]
{
get
Expand All @@ -75,6 +97,11 @@ public IPAddress this[BigInteger i]
#endregion

#region Legacy Enumeration

/// <summary>
/// Gets the current <see cref="IPAddress"/> from the collection.
/// </summary>
/// <returns>The current <see cref="IPAddress"/>.</returns>
public IPAddress Current
{
get
Expand All @@ -91,6 +118,7 @@ object IEnumerator.Current
}
}

/// <inheritdoc />
public bool MoveNext()
{
this._enumerator++;
Expand All @@ -102,11 +130,13 @@ public bool MoveNext()
return true;
}

/// <inheritdoc />
public void Reset()
{
this._enumerator = -1;
}

/// <inheritdoc />
public void Dispose()
{
// nothing to dispose
Expand Down
130 changes: 126 additions & 4 deletions src/System.Net.IPNetwork/IPNetwork2.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ public sealed class IPNetwork2 : IComparable<IPNetwork2>, ISerializable

private AddressFamily _family;

/// <summary>
/// Gets or sets the value of the IPNetwork property.
/// </summary>
[DataMember(Name = "IPNetwork", IsRequired = true)]
public string Value
{
Expand Down Expand Up @@ -224,6 +227,12 @@ public byte Cidr
#if TRAVISCI
public
#else
/// <summary>
/// Initializes a new instance of the <see cref="IPNetwork2"/> class with the specified IP address, address family, and CIDR.
/// </summary>
/// <param name="ipaddress">The IP address of the network.</param>
/// <param name="family">The address family of the network.</param>
/// <param name="cidr">The CIDR (Classless Inter-Domain Routing) notation of the network.</param>
internal
#endif
IPNetwork2(BigInteger ipaddress, AddressFamily family, byte cidr)

Check warning on line 238 in src/System.Net.IPNetwork/IPNetwork2.cs

View workflow job for this annotation

GitHub Actions / build 

Missing XML comment for publicly visible type or member 'IPNetwork2.IPNetwork2(BigInteger, AddressFamily, byte)'
Expand Down Expand Up @@ -1305,7 +1314,7 @@ public bool Contains(IPAddress contains)
{
if (contains == null)
{
throw new ArgumentNullException("ipaddress");
throw new ArgumentNullException("contains");
}

if (this.AddressFamily != contains.AddressFamily)
Expand All @@ -1323,6 +1332,14 @@ public bool Contains(IPAddress contains)
return result;
}

/// <summary>
/// Determines whether the given IP address is part of the given IP network.
/// </summary>
/// <param name="network">The IP network.</param>
/// <param name="ipaddress">The IP address.</param>
/// <returns>
/// <c>true</c> if the IP address is part of the IP network; otherwise, <c>false</c>.
/// </returns>
[Obsolete("static Contains is deprecated, please use instance Contains.")]
public static bool Contains(IPNetwork2 network, IPAddress ipaddress)
{
Expand Down Expand Up @@ -1358,6 +1375,14 @@ public bool Contains(IPNetwork2 contains)
return result;
}

/// <summary>
/// Determines if the given <paramref name="network"/> contains the specified <paramref name="network2"/>.
/// </summary>
/// <param name="network">The network to check for containment.</param>
/// <param name="network2">The network to check if it is contained.</param>
/// <returns>
/// <c>true</c> if the <paramref name="network"/> contains the <paramref name="network2"/>; otherwise, <c>false</c>.
/// </returns>
[Obsolete("static Contains is deprecated, please use instance Contains.")]
public static bool Contains(IPNetwork2 network, IPNetwork2 network2)
{
Expand Down Expand Up @@ -1408,6 +1433,12 @@ public bool Overlap(IPNetwork2 network2)
return overlap;
}

/// <summary>
/// Determines if two IPNetwork2 objects overlap each other.
/// </summary>
/// <param name="network">The first IPNetwork2 object.</param>
/// <param name="network2">The second IPNetwork2 object.</param>
/// <returns>Returns true if the two IPNetwork2 objects overlap, otherwise false.</returns>
[Obsolete("static Overlap is deprecated, please use instance Overlap.")]
public static bool Overlap(IPNetwork2 network, IPNetwork2 network2)
{
Expand All @@ -1423,6 +1454,12 @@ public static bool Overlap(IPNetwork2 network, IPNetwork2 network2)

#region ToString

/// <summary>
/// Returns a string representation of the object.
/// </summary>
/// <returns>
/// A string representation of the object which includes the Network and Cidr values separated by a "/".
/// </returns>
public override string ToString()
{
return string.Format("{0}/{1}", this.Network, this.Cidr);
Expand All @@ -1439,7 +1476,7 @@ public override string ToString()
/// <summary>
/// Gets 10.0.0.0/8.
/// </summary>
/// <returns>The IANA reserved IPNetwork 10.0.0.0/8.<returns>
/// <returns>The IANA reserved IPNetwork 10.0.0.0/8.</returns>
public static IPNetwork2 IANA_ABLK_RESERVED1
{
get
Expand All @@ -1463,7 +1500,7 @@ public static IPNetwork2 IANA_BBLK_RESERVED1
/// <summary>
/// Gets 192.168.0.0/16.
/// </summary>
/// <returns>The IANA reserved IPNetwork 192.168.0.0/16.<returns>
/// <returns>The IANA reserved IPNetwork 192.168.0.0/16.</returns>
public static IPNetwork2 IANA_CBLK_RESERVED1
{
get
Expand Down Expand Up @@ -1502,6 +1539,21 @@ public bool IsIANAReserved()
|| IPNetwork2.IANA_CBLK_RESERVED1.Contains(this);
}

/// <summary>
/// Determines whether the specified IP network is reserved according to the IANA Reserved ranges.
/// </summary>
/// <param name="ipnetwork">The IP network to check.</param>
/// <returns>
/// <c>true</c> if the specified IP network is reserved according to the IANA Reserved ranges; otherwise, <c>false</c>.
/// </returns>
/// <remarks>
/// <para>
/// This method is obsolete and should not be used. Please use the instance method <see cref="IsIANAReserved"/> instead.

Check warning on line 1551 in src/System.Net.IPNetwork/IPNetwork2.cs

View workflow job for this annotation

GitHub Actions / build 

Ambiguous reference in cref attribute: 'IsIANAReserved'. Assuming 'IPNetwork2.IsIANAReserved(IPAddress)', but could have also matched other overloads including 'IPNetwork2.IsIANAReserved()'.
/// </para>
/// <para>
/// Throws an <see cref="ArgumentNullException"/> if <paramref name="ipnetwork"/> is <c>null</c>.
/// </para>
/// </remarks>
[Obsolete("static IsIANAReserved is deprecated, please use instance IsIANAReserved.")]
public static bool IsIANAReserved(IPNetwork2 ipnetwork)
{
Expand Down Expand Up @@ -1531,6 +1583,14 @@ public IPNetworkCollection Subnet(byte cidr)
return ipnetworkCollection;
}

/// <summary>
/// Subnet method is used to divide the given IP network into subnets with the specified CIDR.
/// </summary>
/// <param name="network">The IP network to be subnetted.</param>
/// <param name="cidr">The CIDR (Classless Inter-Domain Routing) value used to subnet the network.</param>
/// <returns>
/// A collection of subnets created from the given network using the specified CIDR.
/// </returns>
[Obsolete("static Subnet is deprecated, please use instance Subnet.")]
public static IPNetworkCollection Subnet(IPNetwork2 network, byte cidr)
{
Expand Down Expand Up @@ -1563,6 +1623,15 @@ public bool TrySubnet(byte cidr, out IPNetworkCollection ipnetworkCollection)
return true;
}

/// <summary>
/// Subnet a network into multiple nets of cidr mask
/// Subnet 192.168.0.0/24 into cidr 25 gives 192.168.0.0/25, 192.168.0.128/25
/// Subnet 10.0.0.0/8 into cidr 9 gives 10.0.0.0/9, 10.128.0.0/9.
/// </summary>
/// <param name="network"></param>
/// <param name="cidr">A byte representing the CIDR to be used to subnet the current IPNetwork.</param>
/// <param name="ipnetworkCollection">The resulting subnetted IPNetwork.</param>
/// <returns>true if network was split successfully; otherwise, false.</returns>
[Obsolete("static TrySubnet is deprecated, please use instance TrySubnet.")]
public static bool TrySubnet(IPNetwork2 network, byte cidr, out IPNetworkCollection ipnetworkCollection)
{
Expand Down Expand Up @@ -1637,6 +1706,15 @@ public IPNetwork2 Supernet(IPNetwork2 network2)
return supernet;
}

/// <summary>
/// Supernet two consecutive cidr equal subnet into a single one
/// 192.168.0.0/24 + 192.168.1.0/24 = 192.168.0.0/23
/// 10.1.0.0/16 + 10.0.0.0/16 = 10.0.0.0/15
/// 192.168.0.0/24 + 192.168.0.0/25 = 192.168.0.0/24.
/// </summary>
/// <param name="network"></param>
/// <param name="network2">The network to supernet with.</param>
/// <returns>A supernetted IP Network.</returns>
[Obsolete("static Supernet is deprecated, please use instance Supernet.")]
public static IPNetwork2 Supernet(IPNetwork2 network, IPNetwork2 network2)
{
Expand All @@ -1660,6 +1738,16 @@ public bool TrySupernet(IPNetwork2 network2, out IPNetwork2 supernet)
return parsed;
}

/// <summary>
/// Try to supernet two consecutive cidr equal subnet into a single one
/// 192.168.0.0/24 + 192.168.1.0/24 = 192.168.0.0/23
/// 10.1.0.0/16 + 10.0.0.0/16 = 10.0.0.0/15
/// 192.168.0.0/24 + 192.168.0.0/25 = 192.168.0.0/24.
/// </summary>
/// <param name="network"></param>
/// <param name="network2">The network to supernet with.</param>
/// <param name="supernet">The resulting IPNetwork.</param>
/// <returns>true if network2 was supernetted successfully; otherwise, false.</returns>
[Obsolete("static TrySupernet is deprecated, please use instance TrySupernet.")]
public static bool TrySupernet(IPNetwork2 network, IPNetwork2 network2, out IPNetwork2 supernet)
{
Expand Down Expand Up @@ -1736,7 +1824,7 @@ static void InternalSupernet(bool trySupernet, IPNetwork2 network1, IPNetwork2 n
{
if (trySupernet == false)
{
throw new ArgumentOutOfRangeException("network");
throw new ArgumentOutOfRangeException("network1");
}

supernet = null;
Expand Down Expand Up @@ -1766,6 +1854,7 @@ static void InternalSupernet(bool trySupernet, IPNetwork2 network1, IPNetwork2 n

#region GetHashCode

/// <inheritdoc />
public override int GetHashCode()
{
return this._hashCode;
Expand Down Expand Up @@ -1931,6 +2020,15 @@ private static void RemoveNull(List<IPNetwork2> ipns)

#region WideSubnet

/// <summary>
/// Finds the widest subnet that can contain both the start and end IP addresses.
/// </summary>
/// <param name="start">The starting IP address.</param>
/// <param name="end">The ending IP address.</param>
/// <returns>The widest subnet that contains both the start and end IP addresses.</returns>
/// <exception cref="ArgumentNullException">Thrown when either the start or end IP address is null or empty.</exception>
/// <exception cref="ArgumentException">Thrown when the start or end IP addresses are not valid.</exception>
/// <exception cref="NotSupportedException">Thrown when the start and end IP addresses have different address families.</exception>
public static IPNetwork2 WideSubnet(string start, string end)
{
if (string.IsNullOrEmpty(start))
Expand Down Expand Up @@ -1972,6 +2070,12 @@ public static IPNetwork2 WideSubnet(string start, string end)
return ipnetwork;
}

/// <summary>
/// Attempts to find the widest subnet that contains both the start and end IP addresses. objects.
/// </summary>
/// <param name="ipnetworks">An array of IPNetwork2 objects to wide subnet.</param>
/// <param name="ipnetwork">When this method returns, contains the wide subnet of the IPNetwork2 objects, if wide subnet was successful; otherwise, null.</param>
/// <returns>true if wide subnet was successful; otherwise, false.</returns>
public static bool TryWideSubnet(IPNetwork2[] ipnetworks, out IPNetwork2 ipnetwork)
{
IPNetwork2.InternalWideSubnet(true, ipnetworks, out IPNetwork2 ipn);
Expand All @@ -1986,6 +2090,9 @@ public static bool TryWideSubnet(IPNetwork2[] ipnetworks, out IPNetwork2 ipnetwo
return true;
}

/// <summary>
/// Finds the widest subnet from an array of IP networks. </summary> <param name="ipnetworks">An array of IPNetwork2 objects representing the IP networks.</param> <returns>The widest subnet as an IPNetwork2 object.</returns>
/// /
public static IPNetwork2 WideSubnet(IPNetwork2[] ipnetworks)
{
IPNetwork2.InternalWideSubnet(false, ipnetworks, out IPNetwork2 ipn);
Expand Down Expand Up @@ -2085,6 +2192,10 @@ public string Print()
}
}

/// <summary>
/// Print an ipnetwork in a clear representation string.
/// </summary>
/// <returns>Dump an IPNetwork representation as string.</returns>
[Obsolete("static Print is deprecated, please use instance Print.")]
public static string Print(IPNetwork2 ipnetwork)
{
Expand Down Expand Up @@ -2166,6 +2277,17 @@ public IPAddressCollection ListIPAddress(FilterEnum filter = FilterEnum.All)

#region IComparable<IPNetwork> Members

/// <summary>
/// Compares two IPNetwork2 instances.
/// </summary>
/// <param name="left">The first IPNetwork2 instance to compare.</param>
/// <param name="right">The second IPNetwork2 instance to compare.</param>
/// <returns>
/// A value indicating the relative order of the two IPNetwork2 instances.
/// Zero if the instances are equal.
/// A negative value if <paramref name="left"/> is less than <paramref name="right"/>.
/// A positive value if <paramref name="left"/> is greater than <paramref name="right"/>.
/// </returns>
public static int Compare(IPNetwork2 left, IPNetwork2 right)
{
// two null IPNetworks are equal
Expand Down
Loading

0 comments on commit 137a12e

Please sign in to comment.