From fa7cb20fe9125b8a4a1dcac6e3c92749bb6e3865 Mon Sep 17 00:00:00 2001 From: lduchosal Date: Thu, 18 Jan 2024 10:00:15 +0100 Subject: [PATCH 1/2] Fix: documentations --- .../IPAddressCollection.cs | 26 ++++- src/System.Net.IPNetwork/IPNetwork2.cs | 104 ++++++++++++++++++ .../IPNetworkCollection.cs | 25 +++++ 3 files changed, 154 insertions(+), 1 deletion(-) diff --git a/src/System.Net.IPNetwork/IPAddressCollection.cs b/src/System.Net.IPNetwork/IPAddressCollection.cs index b48a9a3..5bcf6ef 100644 --- a/src/System.Net.IPNetwork/IPAddressCollection.cs +++ b/src/System.Net.IPNetwork/IPAddressCollection.cs @@ -8,6 +8,9 @@ namespace System.Net using System.Collections.Generic; using System.Numerics; + /// + /// Enum representing different filters for a collection of items. + /// public enum FilterEnum { All, @@ -15,7 +18,7 @@ public enum FilterEnum } /// - /// A collection of IP Adresses + /// Represents a collection of IP addresses within a specific IP network. /// public class IPAddressCollection : IEnumerable, IEnumerator { @@ -31,6 +34,13 @@ internal IPAddressCollection(IPNetwork2 ipnetwork, FilterEnum filter) } #region Count, Array, Enumerator + + /// + /// Gets the count of IP addresses within the network. + /// + /// + /// The count of IP addresses within the network. + /// public BigInteger Count { get @@ -50,6 +60,12 @@ public BigInteger Count } } + /// + /// Gets the IP address corresponding to the given index from the IPNetwork collection. + /// + /// The index of the IP address to retrieve. + /// The IP address corresponding to the given index. + /// Thrown when the given index is greater than or equal to the Count property of the IPNetwork collection. public IPAddress this[BigInteger i] { get @@ -75,6 +91,11 @@ public IPAddress this[BigInteger i] #endregion #region Legacy Enumeration + + /// + /// Gets the current from the collection. + /// + /// The current . public IPAddress Current { get @@ -91,6 +112,7 @@ object IEnumerator.Current } } + /// public bool MoveNext() { this._enumerator++; @@ -102,11 +124,13 @@ public bool MoveNext() return true; } + /// public void Reset() { this._enumerator = -1; } + /// public void Dispose() { // nothing to dispose diff --git a/src/System.Net.IPNetwork/IPNetwork2.cs b/src/System.Net.IPNetwork/IPNetwork2.cs index e1b8854..f7deea9 100644 --- a/src/System.Net.IPNetwork/IPNetwork2.cs +++ b/src/System.Net.IPNetwork/IPNetwork2.cs @@ -21,6 +21,7 @@ public sealed class IPNetwork2 : IComparable, ISerializable { #region properties + /// , ISerializable private AddressFamily _family; + /// + /// Gets or sets the value of the IPNetwork property. + /// [DataMember(Name = "IPNetwork", IsRequired = true)] public string Value { @@ -224,6 +228,12 @@ public byte Cidr #if TRAVISCI public #else + /// + /// Initializes a new instance of the class with the specified IP address, address family, and CIDR. + /// + /// The IP address of the network. + /// The address family of the network. + /// The CIDR (Classless Inter-Domain Routing) notation of the network. internal #endif IPNetwork2(BigInteger ipaddress, AddressFamily family, byte cidr) @@ -1312,6 +1322,14 @@ public bool Contains(IPAddress contains) return result; } + /// + /// Determines whether the given IP address is part of the given IP network. + /// + /// The IP network. + /// The IP address. + /// + /// true if the IP address is part of the IP network; otherwise, false. + /// [Obsolete("static Contains is deprecated, please use instance Contains.")] public static bool Contains(IPNetwork2 network, IPAddress ipaddress) { @@ -1347,6 +1365,14 @@ public bool Contains(IPNetwork2 contains) return result; } + /// + /// Determines if the given contains the specified . + /// + /// The network to check for containment. + /// The network to check if it is contained. + /// + /// true if the contains the ; otherwise, false. + /// [Obsolete("static Contains is deprecated, please use instance Contains.")] public static bool Contains(IPNetwork2 network, IPNetwork2 network2) { @@ -1397,6 +1423,12 @@ public bool Overlap(IPNetwork2 network2) return overlap; } + /// + /// Determines if two IPNetwork2 objects overlap each other. + /// + /// The first IPNetwork2 object. + /// The second IPNetwork2 object. + /// Returns true if the two IPNetwork2 objects overlap, otherwise false. [Obsolete("static Overlap is deprecated, please use instance Overlap.")] public static bool Overlap(IPNetwork2 network, IPNetwork2 network2) { @@ -1412,6 +1444,12 @@ public static bool Overlap(IPNetwork2 network, IPNetwork2 network2) #region ToString + /// + /// Returns a string representation of the object. + /// + /// + /// A string representation of the object which includes the Network and Cidr values separated by a "/". + /// public override string ToString() { return string.Format("{0}/{1}", this.Network, this.Cidr); @@ -1491,6 +1529,21 @@ public bool IsIANAReserved() || IPNetwork2.IANA_CBLK_RESERVED1.Contains(this); } + /// + /// Determines whether the specified IP network is reserved according to the IANA Reserved ranges. + /// + /// The IP network to check. + /// + /// true if the specified IP network is reserved according to the IANA Reserved ranges; otherwise, false. + /// + /// + /// + /// This method is obsolete and should not be used. Please use the instance method instead. + /// + /// + /// Throws an if is null. + /// + /// [Obsolete("static IsIANAReserved is deprecated, please use instance IsIANAReserved.")] public static bool IsIANAReserved(IPNetwork2 ipnetwork) { @@ -1520,6 +1573,14 @@ public IPNetworkCollection Subnet(byte cidr) return ipnetworkCollection; } + /// + /// Subnet method is used to divide the given IP network into subnets with the specified CIDR. + /// + /// The IP network to be subnetted. + /// The CIDR (Classless Inter-Domain Routing) value used to subnet the network. + /// + /// A collection of subnets created from the given network using the specified CIDR. + /// [Obsolete("static Subnet is deprecated, please use instance Subnet.")] public static IPNetworkCollection Subnet(IPNetwork2 network, byte cidr) { @@ -1649,6 +1710,15 @@ public bool TrySupernet(IPNetwork2 network2, out IPNetwork2 supernet) return parsed; } + /// + /// 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. + /// + /// The network to supernet with. + /// The resulting IPNetwork. + /// true if network2 was supernetted successfully; otherwise, false. [Obsolete("static TrySupernet is deprecated, please use instance TrySupernet.")] public static bool TrySupernet(IPNetwork2 network, IPNetwork2 network2, out IPNetwork2 supernet) { @@ -1755,6 +1825,7 @@ static void InternalSupernet(bool trySupernet, IPNetwork2 network1, IPNetwork2 n #region GetHashCode + /// public override int GetHashCode() { return this._hashCode; @@ -1920,6 +1991,15 @@ private static void RemoveNull(List ipns) #region WideSubnet + /// + /// Finds the widest subnet that can contain both the start and end IP addresses. + /// + /// The starting IP address. + /// The ending IP address. + /// The widest subnet that contains both the start and end IP addresses. + /// Thrown when either the start or end IP address is null or empty. + /// Thrown when the start or end IP addresses are not valid. + /// Thrown when the start and end IP addresses have different address families. public static IPNetwork2 WideSubnet(string start, string end) { if (string.IsNullOrEmpty(start)) @@ -1961,6 +2041,12 @@ public static IPNetwork2 WideSubnet(string start, string end) return ipnetwork; } + /// + /// Attempts to find the widest subnet that contains both the start and end IP addresses. objects. + /// + /// An array of IPNetwork2 objects to wide subnet. + /// When this method returns, contains the wide subnet of the IPNetwork2 objects, if wide subnet was successful; otherwise, null. + /// true if wide subnet was successful; otherwise, false. public static bool TryWideSubnet(IPNetwork2[] ipnetworks, out IPNetwork2 ipnetwork) { IPNetwork2.InternalWideSubnet(true, ipnetworks, out IPNetwork2 ipn); @@ -1975,6 +2061,9 @@ public static bool TryWideSubnet(IPNetwork2[] ipnetworks, out IPNetwork2 ipnetwo return true; } + /// + /// Finds the widest subnet from an array of IP networks. An array of IPNetwork2 objects representing the IP networks. The widest subnet as an IPNetwork2 object. + /// / public static IPNetwork2 WideSubnet(IPNetwork2[] ipnetworks) { IPNetwork2.InternalWideSubnet(false, ipnetworks, out IPNetwork2 ipn); @@ -2074,6 +2163,10 @@ public string Print() } } + /// + /// Print an ipnetwork in a clear representation string. + /// + /// Dump an IPNetwork representation as string. [Obsolete("static Print is deprecated, please use instance Print.")] public static string Print(IPNetwork2 ipnetwork) { @@ -2155,6 +2248,17 @@ public IPAddressCollection ListIPAddress(FilterEnum filter = FilterEnum.All) #region IComparable Members + /// + /// Compares two IPNetwork2 instances. + /// + /// The first IPNetwork2 instance to compare. + /// The second IPNetwork2 instance to compare. + /// + /// A value indicating the relative order of the two IPNetwork2 instances. + /// Zero if the instances are equal. + /// A negative value if is less than . + /// A positive value if is greater than . + /// public static int Compare(IPNetwork2 left, IPNetwork2 right) { // two null IPNetworks are equal diff --git a/src/System.Net.IPNetwork/IPNetworkCollection.cs b/src/System.Net.IPNetwork/IPNetworkCollection.cs index ea9f570..16dd842 100644 --- a/src/System.Net.IPNetwork/IPNetworkCollection.cs +++ b/src/System.Net.IPNetwork/IPNetworkCollection.cs @@ -8,6 +8,9 @@ namespace System.Net using System.Collections.Generic; using System.Numerics; + /// + /// Represents a collection of IP networks based on a given parent IP network and subnet CIDR. + /// public class IPNetworkCollection : IEnumerable, IEnumerator { private BigInteger _enumerator; @@ -37,6 +40,14 @@ private BigInteger _network #if TRAVISCI public #else + /// + /// Initializes a new instance of the class. + /// Represents a collection of IP networks based on a given parent IP network and subnet CIDR. + /// + /// + /// This class is used to generate a collection of IP networks by dividing the given parent IP network into subnets based on the provided subnet CIDR (Classless Inter-Domain Routing + /// ) value. + /// internal #endif IPNetworkCollection(IPNetwork2 ipnetwork, byte cidrSubnet) @@ -59,6 +70,9 @@ private BigInteger _network #region Count, Array, Enumerator + /// + /// Gets the total number of IP addresses in the subnet. + /// public BigInteger Count { get @@ -90,11 +104,13 @@ public IPNetwork2 this[BigInteger i] #region IEnumerable Members + /// IEnumerator IEnumerable.GetEnumerator() { return this; } + /// IEnumerator IEnumerable.GetEnumerator() { return this; @@ -102,6 +118,7 @@ IEnumerator IEnumerable.GetEnumerator() #region IEnumerator Members + /// public IPNetwork2 Current { get { return this[this._enumerator]; } @@ -111,6 +128,14 @@ public IPNetwork2 Current #region IDisposable Members + /// + /// Releases all resources used by the object. + /// + /// + /// This method implements the IDisposable interface and releases any resources + /// held by the object. In this particular implementation, there are no resources + /// to dispose of, so the method does nothing. + /// public void Dispose() { // nothing to dispose From a60fa7a1fb5ab8ef71717e836f23fc78d593133c Mon Sep 17 00:00:00 2001 From: lduchosal Date: Thu, 18 Jan 2024 10:26:42 +0100 Subject: [PATCH 2/2] Fix: documentation --- .../IPAddressCollection.cs | 8 +++++- src/System.Net.IPNetwork/IPNetwork2.cs | 28 +++++++++++++++---- .../IPNetworkCollection.cs | 18 ++++++++++++ 3 files changed, 48 insertions(+), 6 deletions(-) diff --git a/src/System.Net.IPNetwork/IPAddressCollection.cs b/src/System.Net.IPNetwork/IPAddressCollection.cs index 5bcf6ef..bb7c190 100644 --- a/src/System.Net.IPNetwork/IPAddressCollection.cs +++ b/src/System.Net.IPNetwork/IPAddressCollection.cs @@ -9,11 +9,17 @@ namespace System.Net using System.Numerics; /// - /// Enum representing different filters for a collection of items. + /// Represents different filters for a collection of items. /// public enum FilterEnum { + /// + /// Every IPAdresses are returned + /// All, + /// + /// Returns only usable IPAdresses + /// Usable, } diff --git a/src/System.Net.IPNetwork/IPNetwork2.cs b/src/System.Net.IPNetwork/IPNetwork2.cs index f7deea9..5230984 100644 --- a/src/System.Net.IPNetwork/IPNetwork2.cs +++ b/src/System.Net.IPNetwork/IPNetwork2.cs @@ -21,7 +21,6 @@ public sealed class IPNetwork2 : IComparable, ISerializable { #region properties - /// /// Gets 10.0.0.0/8. /// - /// The IANA reserved IPNetwork 10.0.0.0/8. + /// The IANA reserved IPNetwork 10.0.0.0/8. public static IPNetwork2 IANA_ABLK_RESERVED1 { get @@ -1490,7 +1489,7 @@ public static IPNetwork2 IANA_BBLK_RESERVED1 /// /// Gets 192.168.0.0/16. /// - /// The IANA reserved IPNetwork 192.168.0.0/16. + /// The IANA reserved IPNetwork 192.168.0.0/16. public static IPNetwork2 IANA_CBLK_RESERVED1 { get @@ -1613,6 +1612,15 @@ public bool TrySubnet(byte cidr, out IPNetworkCollection ipnetworkCollection) return true; } + /// + /// 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. + /// + /// + /// A byte representing the CIDR to be used to subnet the current IPNetwork. + /// The resulting subnetted IPNetwork. + /// true if network was split successfully; otherwise, false. [Obsolete("static TrySubnet is deprecated, please use instance TrySubnet.")] public static bool TrySubnet(IPNetwork2 network, byte cidr, out IPNetworkCollection ipnetworkCollection) { @@ -1687,6 +1695,15 @@ public IPNetwork2 Supernet(IPNetwork2 network2) return supernet; } + /// + /// 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. + /// + /// + /// The network to supernet with. + /// A supernetted IP Network. [Obsolete("static Supernet is deprecated, please use instance Supernet.")] public static IPNetwork2 Supernet(IPNetwork2 network, IPNetwork2 network2) { @@ -1716,6 +1733,7 @@ public bool TrySupernet(IPNetwork2 network2, out IPNetwork2 supernet) /// 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. /// + /// /// The network to supernet with. /// The resulting IPNetwork. /// true if network2 was supernetted successfully; otherwise, false. @@ -1795,7 +1813,7 @@ static void InternalSupernet(bool trySupernet, IPNetwork2 network1, IPNetwork2 n { if (trySupernet == false) { - throw new ArgumentOutOfRangeException("network"); + throw new ArgumentOutOfRangeException("network1"); } supernet = null; diff --git a/src/System.Net.IPNetwork/IPNetworkCollection.cs b/src/System.Net.IPNetwork/IPNetworkCollection.cs index 16dd842..b7a9bb4 100644 --- a/src/System.Net.IPNetwork/IPNetworkCollection.cs +++ b/src/System.Net.IPNetwork/IPNetworkCollection.cs @@ -82,6 +82,14 @@ public BigInteger Count } } + /// + /// Retrieves an IPNetwork2 object from the collection by index. + /// + /// The index of the IPNetwork2 object to retrieve. + /// + /// The IPNetwork2 object at the specified index. + /// + /// Thrown when the specified index is greater than or equal to the Count of the collection. public IPNetwork2 this[BigInteger i] { get @@ -151,6 +159,13 @@ object IEnumerator.Current get { return this.Current; } } + /// + /// Moves the enumerator to the next element in the collection. + /// + /// + /// if the enumerator was successfully moved to the next element; + /// if the enumerator has reached the end of the collection. + /// public bool MoveNext() { this._enumerator++; @@ -162,6 +177,9 @@ public bool MoveNext() return true; } + /// + /// Resets the state of the enumerator. + /// public void Reset() { this._enumerator = -1;