adding function header comments

Signed-off-by: Oliver Wegner <[email protected]>

lib/private/Net/AbstractIpAddress.php

@@ -34,6 +34,12 @@ abstract protected function matchCidr(IIpAddress $other): bool;
 	private $netPart = '';
 	private $netmaskBits = 0;
 
+	/**
+	 * Constructor that takes an IP address in string form and
+	 * initializes this instance to represent that address
+	 *
+	 * @param string $address
+	 */
 	public function __construct(string $address) {
 		$this->setOriginal($address);
 
@@ -46,38 +52,93 @@ public function __construct(string $address) {
 		}
 	}
 
+	/**
+	 * Sets the literal address string that this instance
+	 * represents
+	 *
+	 * @param string $original
+	 */
 	protected function setOriginal(string $original) {
 		$this->original = $original;
 	}
 
+	/**
+	 * Returns the literal address string that this instance
+	 * represents
+	 *
+	 * @return string
+	 */
 	protected function getOriginal(): string {
 		return $this->original;
 	}
 
+	/**
+	 * Sets the network part of the
+	 * address/range represented by this instance
+	 *
+	 * @param string $netPart
+	 */
 	protected function setNetPart(string $netPart) {
 		$this->netPart = $netPart;
 	}
 
+	/**
+	 * Returns the network part of the
+	 * address/range represented by this instance
+	 *
+	 * @return string
+	 */
 	protected function getNetPart(): string {
 		return $this->netPart;
 	}
 
+	/**
+	 * Sets the number of bits of the net part of the IP
+	 * address/range represented by this instance
+	 *
+	 * @param int $bits
+	 */
 	protected function setNetmaskBits(int $bits) {
 		$this->netmaskBits = $bits;
 	}
 
+	/**
+	 * Returns the number of bits of the net part of the IP
+	 * address/range represented by this instance
+	 *
+	 * @return int
+	 */
 	protected function getNetmaskBits(): int {
 		return $this->netmaskBits;
 	}
 
+	/**
+	 * Returns whether $other is literally equivalent to this instance
+	 *
+	 * @return bool
+	 */
 	protected function matchOriginal(IIpAddress $other): bool {
 		return $other->getOriginal() === $this->getOriginal();
 	}
 
+	/**
+	 * Returns whether this instance represents an IP range (vs.
+	 * a single IP address)
+	 *
+	 * @return bool
+	 */
 	public function isRange(): bool {
 		return $this->getNetmaskBits() < $this->getMaxBitlength();
 	}
 
+	/**
+	 * Returns whether given $other address is either
+	 * - equal to this instance regarding its IP address   or
+	 * - is contained in the IP address range represented by this instance
+	 *
+	 * @param IIpAddress $other
+	 * @return bool
+	 */
 	public function containsAddress(IIpAddress $other): bool {
 		return $this->isRange()
 			? $this->matchCidr($other)

lib/private/Net/IpAddressFactory.php

@@ -23,15 +23,29 @@
 
 namespace OC\Net;
 
+use OC\Net\IIpAddress;
 use OC\Net\IpAddressV4;
 use OC\Net\IpAddressV6;
 
 class IpAddressFactory {
+	/**
+	 * Returns whether $address represents an IPv6 address
+	 *
+	 * @param string $address
+	 * @return bool
+	 */
 	public static function isIpv6(string $address): bool {
 		return strpos($address, ':') !== false;
 	}
 
-	public static function new($address) {
+	/**
+	 * Creates a new instance conforming to IIpAddress and
+	 * representing the given $address.
+	 *
+	 * @param string $address
+	 * @return IIpAddress
+	 */
+	public static function new($address): IIpAddress {
 		if (self::isIpv6($address)) {
 			return new IpAddressV6($address);
 		} else {

lib/private/Net/IpAddressV4.php

@@ -31,14 +31,32 @@ class IpAddressV4 extends AbstractIpAddress {
 	private $address = '';
 	private $cidrBits = 0;
 
+	/**
+	 * Returns the length of the represented IP address format in bits.
+	 *
+	 * @return int
+	 */
 	public function getMaxBitlength(): int {
 		return 32;
 	}
 
+	/**
+	 * Returns the regular expression for recognizing CIDR notation.
+	 *
+	 * @return string
+	 */
 	protected function getCidrRegex(): string {
 		return '/^([0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3})\/([0-9]{1,2})$/';
 	}
 
+	/**
+	 * Returns whether given $other address is either
+	 * - equal to this instance regarding its IP address   or
+	 * - is contained in the IP address range represented by this instance
+	 *
+	 * @param IIpAddress $other
+	 * @return bool
+	 */
 	protected function matchCidr(IIpAddress $other): bool {
 		$shiftbits = $this->getMaxBitlength() - $this->getNetmaskBits();
 		$thisnum = ip2long($this->getNetPart()) >> $shiftbits;

lib/private/Net/IpAddressV6.php

@@ -31,14 +31,32 @@ class IpAddressV6 extends AbstractIpAddress {
 	private $address = '';
 	private $cidrBits = 0;
 
+	/**
+	 * Returns the length of the represented IP address format in bits.
+	 *
+	 * @return int
+	 */
 	public function getMaxBitlength(): int {
 		return 128;
 	}
 
+	/**
+	 * Returns the regular expression for recognizing CIDR notation.
+	 *
+	 * @return string
+	 */
 	protected function getCidrRegex(): string {
 		return '/^([0-9a-fA-F:]+[0-9a-fA-F:]+)\/([0-9]{1,3})$/';
 	}
 
+	/**
+	 * Returns whether given $other address is either
+	 * - equal to this instance regarding its IP address   or
+	 * - is contained in the IP address range represented by this instance
+	 *
+	 * @param IIpAddress $other
+	 * @return bool
+	 */
 	protected function matchCidr(IIpAddress $other): bool {
 		$thisaddrn = inet_pton($this->getNetPart());
 		$otheraddrn = inet_pton($other->getNetPart());