From 137a12e7c940e58e1f23e73c142110983a13c1d4 Mon Sep 17 00:00:00 2001 From: lduchosal Date: Thu, 18 Jan 2024 11:05:43 +0100 Subject: [PATCH] Fix documentation (#302) * Fix: documentations * Fix: documentation --------- Co-authored-by: lduchosal --- .../IPAddressCollection.cs | 32 ++++- src/System.Net.IPNetwork/IPNetwork2.cs | 130 +++++++++++++++++- .../IPNetworkCollection.cs | 41 ++++-- 3 files changed, 190 insertions(+), 13 deletions(-) diff --git a/src/System.Net.IPNetwork/IPAddressCollection.cs b/src/System.Net.IPNetwork/IPAddressCollection.cs index b48a9a3..bb7c190 100644 --- a/src/System.Net.IPNetwork/IPAddressCollection.cs +++ b/src/System.Net.IPNetwork/IPAddressCollection.cs @@ -8,14 +8,23 @@ namespace System.Net using System.Collections.Generic; using System.Numerics; + /// + /// Represents different filters for a collection of items. + /// public enum FilterEnum { + /// + /// Every IPAdresses are returned + /// All, + /// + /// Returns only usable IPAdresses + /// Usable, } /// - /// A collection of IP Adresses + /// Represents a collection of IP addresses within a specific IP network. /// public class IPAddressCollection : IEnumerable, IEnumerator { @@ -31,6 +40,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 +66,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 +97,11 @@ public IPAddress this[BigInteger i] #endregion #region Legacy Enumeration + + /// + /// Gets the current from the collection. + /// + /// The current . public IPAddress Current { get @@ -91,6 +118,7 @@ object IEnumerator.Current } } + /// public bool MoveNext() { this._enumerator++; @@ -102,11 +130,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 9e5b867..df14c7e 100644 --- a/src/System.Net.IPNetwork/IPNetwork2.cs +++ b/src/System.Net.IPNetwork/IPNetwork2.cs @@ -29,6 +29,9 @@ public sealed class IPNetwork2 : IComparable, ISerializable private AddressFamily _family; + /// + /// Gets or sets the value of the IPNetwork property. + /// [DataMember(Name = "IPNetwork", IsRequired = true)] public string Value { @@ -224,6 +227,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) @@ -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) @@ -1323,6 +1332,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) { @@ -1358,6 +1375,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) { @@ -1408,6 +1433,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) { @@ -1423,6 +1454,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); @@ -1439,7 +1476,7 @@ public override string ToString() /// /// 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 @@ -1463,7 +1500,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 @@ -1502,6 +1539,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) { @@ -1531,6 +1583,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) { @@ -1563,6 +1623,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) { @@ -1637,6 +1706,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) { @@ -1660,6 +1738,16 @@ 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) { @@ -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; @@ -1766,6 +1854,7 @@ static void InternalSupernet(bool trySupernet, IPNetwork2 network1, IPNetwork2 n #region GetHashCode + /// public override int GetHashCode() { return this._hashCode; @@ -1931,6 +2020,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)) @@ -1972,6 +2070,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); @@ -1986,6 +2090,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); @@ -2085,6 +2192,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) { @@ -2166,6 +2277,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 e694832..9fba022 100644 --- a/src/System.Net.IPNetwork/IPNetworkCollection.cs +++ b/src/System.Net.IPNetwork/IPNetworkCollection.cs @@ -9,7 +9,7 @@ namespace System.Net using System.Numerics; /// - /// A collection of IPNetwork2 + /// Represents a collection of IP networks based on a given parent IP network and subnet CIDR. /// public class IPNetworkCollection : IEnumerable, IEnumerator { @@ -40,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) @@ -63,7 +71,7 @@ private BigInteger _network #region Count, Array, Enumerator /// - /// Count the nnumber of IPAddresses in a IPNetworkCollection + /// Gets the total number of IP addresses in the subnet. /// public BigInteger Count { @@ -74,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 @@ -96,11 +112,13 @@ public IPNetwork2 this[BigInteger i] #region IEnumerable Members + /// IEnumerator IEnumerable.GetEnumerator() { return this; } + /// IEnumerator IEnumerable.GetEnumerator() { return this; @@ -108,9 +126,7 @@ IEnumerator IEnumerable.GetEnumerator() #region IEnumerator Members - /// - /// Gets the current IEnumerator item - /// + /// public IPNetwork2 Current { get { return this[this._enumerator]; } @@ -121,7 +137,13 @@ public IPNetwork2 Current #region IDisposable Members /// - /// Dispose the IPNetwork instance + /// 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() { @@ -141,9 +163,12 @@ object IEnumerator.Current } /// - /// Advances the enumerator to the next element of the collection. + /// Moves the enumerator to the next element in the collection. /// - /// true if the enumerator was successfully advanced to the next element; false if the enumerator has passed the end of 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++;