Refs #4200, tweaked docs for core/IP.php.

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