diff --git a/core/IP.php b/core/IP.php
index df22099971a0f8430c7709729fdf11d6bc906d5a..01210577a2252a7a5979a09f990451336cd9a757 100644
--- a/core/IP.php
+++ b/core/IP.php
@@ -12,7 +12,7 @@
namespace Piwik;
/**
- * Handling IP addresses (both IPv4 and IPv6).
+ * Contains IP address helper functions (for both IPv4 and IPv6).
*
* As of Piwik 1.3, IP addresses are stored in the DB has VARBINARY(16),
* and passed around in network address format which has the advantage of
@@ -34,9 +34,9 @@ class IP
const MAPPED_IPv4_START = '::ffff:';
/**
- * Sanitize human-readable IP address.
+ * Removes the port and the last portion of a CIDR IP address.
*
- * @param string $ipString IP address
+ * @param string $ipString The IP address to sanitize.
* @return string
*/
public static function sanitizeIp($ipString)
@@ -126,10 +126,10 @@ class IP
}
/**
- * Convert presentation format IP address to network address format
+ * Convert presentation format IP address to network address format.
*
- * @param string $ipString IP address, either IPv4 or IPv6, e.g., "127.0.0.1"
- * @return string Binary-safe string, e.g., "\x7F\x00\x00\x01"
+ * @param string $ipString IP address, either IPv4 or IPv6, e.g., `"127.0.0.1"`.
+ * @return string Binary-safe string, e.g., `"\x7F\x00\x00\x01"`.
*/
public static function P2N($ipString)
{
@@ -139,12 +139,12 @@ class IP
}
/**
- * Convert network address format to presentation format
+ * Convert network address format to presentation format.
*
- * @see prettyPrint()
+ * See also [prettyPreint](#prettyPrint).
*
- * @param string $ip IP address in network address format
- * @return string IP address in presentation format
+ * @param string $ip IP address in network address format.
+ * @return string IP address in presentation format.
*/
public static function N2P($ip)
{
@@ -154,10 +154,10 @@ class IP
}
/**
- * Alias for N2P()
+ * Alias for [N2P()](#N2P).
*
- * @param string $ip IP address in network address format
- * @return string IP address in presentation format
+ * @param string $ip IP address in network address format.
+ * @return string IP address in presentation format.
*/
public static function prettyPrint($ip)
{
@@ -165,10 +165,11 @@ class IP
}
/**
- * Is this an IPv4, IPv4-compat, or IPv4-mapped address?
+ * Returns true if `$ip` is an IPv4, IPv4-compat, or IPv4-mapped address, false
+ * if otherwise.
*
- * @param string $ip IP address in network address format
- * @return bool True if IPv4, else false
+ * @param string $ip IP address in network address format.
+ * @return bool True if IPv4, else false.
*/
public static function isIPv4($ip)
{
@@ -201,8 +202,8 @@ class IP
* This function does not support the long (or its string representation)
* returned by the built-in ip2long() function, from Piwik 1.3 and earlier.
*
- * @param string $ip IPv4 address in network address format
- * @return string IP address in presentation format
+ * @param string $ip IPv4 address in network address format.
+ * @return string IP address in presentation format.
*/
public static function long2ip($ip)
{
@@ -248,7 +249,10 @@ class IP
}
/**
- * Returns
+ * Returns an IPv4 address from a 'mapped' IPv6 address.
+ *
+ * @param string $ip eg, `'::ffff:192.0.2.128'`
+ * @return string eg, `'192.0.2.128'`
*/
public static function getIPv4FromMappedIPv6($ip)
{
@@ -258,8 +262,8 @@ class IP
/**
* Get low and high IP addresses for a specified range.
*
- * @param array $ipRange An IP address range in presentation format
- * @return array|bool Array ($lowIp, $highIp) in network address format, or false if failure
+ * @param array $ipRange An IP address range in presentation format.
+ * @return array|bool Array `array($lowIp, $highIp)` in network address format, or false on failure.
*/
public static function getIpsForRange($ipRange)
{
@@ -338,10 +342,10 @@ class IP
}
/**
- * Returns the best possible IP of the current user, in the format A.B.C.D
- * For example, this could be the proxy client's IP address.
+ * Returns the most accurate IP address availble for the current user, in
+ * IPv4 format. This could be the proxy client's IP address.
*
- * @return string IP address in presentation format
+ * @return string IP address in presentation format.
*/
public static function getIpFromHeader()
{
@@ -360,10 +364,10 @@ class IP
}
/**
- * Returns a non-proxy IP address from header
+ * Returns a non-proxy IP address from header.
*
- * @param string $default Default value to return if no matching proxy header
- * @param array $proxyHeaders List of proxy headers
+ * @param string $default Default value to return if there no matching proxy header.
+ * @param array $proxyHeaders List of proxy headers.
* @return string
*/
public static function getNonProxyIpFromHeader($default, $proxyHeaders)
@@ -395,9 +399,9 @@ class IP
/**
* Returns the last IP address in a comma separated list, subject to an optional exclusion list.
*
- * @param string $csv Comma separated list of elements
- * @param array $excludedIps Optional list of excluded IP addresses (or IP address ranges)
- * @return string Last (non-excluded) IP address in the list
+ * @param string $csv Comma separated list of elements.
+ * @param array $excludedIps Optional list of excluded IP addresses (or IP address ranges).
+ * @return string Last (non-excluded) IP address in the list.
*/
public static function getLastIpFromList($csv, $excludedIps = null)
{
@@ -415,10 +419,10 @@ class IP
}
/**
- * Get hostname for a given IP address
+ * Get hostname for a given IP address.
*
- * @param string $ipStr Human-readable IP address
- * @return string Hostname or unmodified $ipStr if failure
+ * @param string $ipStr Human-readable IP address.
+ * @return string The hostname or unmodified $ipStr on failure.
*/
public static function getHostByAddr($ipStr)
{
@@ -427,4 +431,4 @@ class IP
$host = strtolower(@gethostbyaddr($ipStr));
return $host === '' ? $ipStr : $host;
}
-}
+}
\ No newline at end of file