From d1ff03cd1daf9ef88fadad25d0c305448b6283d3 Mon Sep 17 00:00:00 2001
From: Aaron Schulz <aaron@users.mediawiki.org>
Date: Mon, 23 Apr 2007 18:06:37 +0000
Subject: [PATCH] *Document some older functions

---
 includes/ProxyTools.php | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/includes/ProxyTools.php b/includes/ProxyTools.php
index aaf2ee163e..ad5b22c794 100644
--- a/includes/ProxyTools.php
+++ b/includes/ProxyTools.php
@@ -3,6 +3,12 @@
  * Functions for dealing with proxies
  */
 
+/**
+ * Extracts the XFF string from the request header
+ * Checks first for "X-Forwarded-For", then "Client-ip"
+ * Note: headers are spoofable
+ * @return string
+ */
 function wfGetForwardedFor() {
 	if( function_exists( 'apache_request_headers' ) ) {
 		// More reliable than $_SERVER due to case and -/_ folding
@@ -44,6 +50,11 @@ function wfGetClientIPfromXFF( $xff ) {
 	return null;
 }
 
+/**
+ * Returns the browser/OS data from the request header
+ * Note: headers are spoofable
+ * @return string
+ */
 function wfGetAgent() {
 	if( function_exists( 'apache_request_headers' ) ) {
 		// More reliable than $_SERVER due to case and -/_ folding
@@ -61,7 +72,11 @@ function wfGetAgent() {
 	}
 }
 
-/** Work out the IP address based on various globals */
+/**
+ * Work out the IP address based on various globals
+ * For trusted proxies, use the XFF client IP (first of the chain)
+ * @return string
+ */
 function wfGetIP() {
 	global $wgIP;
 
@@ -106,6 +121,13 @@ function wfGetIP() {
 	return $ip;
 }
 
+/**
+ * Checks if an IP is a trusted proxy providor
+ * Useful to tell if X-Fowarded-For data is possibly bogus
+ * Squid cache servers for the site and AOL are whitelisted
+ * @param string $ip
+ * @return bool
+ */
 function wfIsTrustedProxy( $ip ) {
 	global $wgSquidServers, $wgSquidServersNoPurge;
 
@@ -170,6 +192,7 @@ function wfProxyCheck() {
 
 /**
  * Convert a network specification in CIDR notation to an integer network and a number of bits
+ * @return array(string, int)
  */
 function wfParseCIDR( $range ) {
 	return IP::parseCIDR( $range );
@@ -177,6 +200,7 @@ function wfParseCIDR( $range ) {
 
 /**
  * Check if an IP address is in the local proxy list
+ * @return bool
  */
 function wfIsLocallyBlockedProxy( $ip ) {
 	global $wgProxyList;
@@ -209,6 +233,7 @@ function wfIsLocallyBlockedProxy( $ip ) {
 /**
  * TODO: move this list to the database in a global IP info table incorporating
  * trusted ISP proxies, blocked IP addresses and open proxies.
+ * @return bool
  */
 function wfIsAOLProxy( $ip ) {
 	$ranges = array(
-- 
2.20.1