phpdoc for wp-settings.php. Fixes #5211 props darkdragon.

git-svn-id: http://svn.automattic.com/wordpress/trunk@6434 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-settings.php

@@ -1,5 +1,23 @@
 <?php
-// Turn register globals off
+/**
+ * Used to setup and fix common variables and include
+ * the WordPress procedural and class library.
+ *
+ * You should not have to change this file and allows for some configuration
+ * in wp-config.php.
+ *
+ * @package WordPress
+ * @since 1.5
+ */
+
+/**
+ * Turn register globals off
+ *
+ * @access private
+ * @package WordPress
+ * @since 2.0
+ * @return null Will return null if register_globals PHP directive was disabled
+ */
 function wp_unregister_GLOBALS() {
 	if ( !ini_get('register_globals') )
 		return;
@@ -22,6 +40,13 @@ function wp_unregister_GLOBALS() {
 
 unset( $wp_filter, $wp_action, $cache_lastcommentmodified, $cache_lastpostdate );
 
+/**
+ * The $blog_id global, which you can change in the config allows you to create a simple
+ * multiple blog installation using just one WordPress and changing $blog_id around.
+ *
+ * @global int $blog_id
+ * @since 2.0
+ */
 if ( ! isset($blog_id) )
 	$blog_id = 1;
 
@@ -71,6 +96,15 @@ function wp_unregister_GLOBALS() {
 if ( !extension_loaded('mysql') && !file_exists(ABSPATH . 'wp-content/db.php') )
 	die( 'Your PHP installation appears to be missing the MySQL which is required for WordPress.' );
 
+/**
+ * PHP 4 standard microtime start capture
+ *
+ * @access private
+ * @package WordPress
+ * @global int $timestart Seconds and Microseconds added together from when function is called
+ * @return bool Always returns true
+ * @since 1.5
+ */
 function timer_start() {
 	global $timestart;
 	$mtime = explode(' ', microtime() );
@@ -79,6 +113,31 @@ function timer_start() {
 	return true;
 }
 
+/**
+ * Return and/or display the time from the page start to when function is called.
+ *
+ * You can get the results and print them by doing:
+ * <code>
+ * $nTimePageTookToExecute = timer_stop();
+ * echo $nTimePageTookToExecute;
+ * </code>
+ *
+ * Or instead, you can do:
+ * <code>
+ * timer_stop(1);
+ * </code>
+ * which will do what the above does. If you need the result, you can assign it to a variable, but
+ * most cases, you only need to echo it.
+ *
+ * @package WordPress
+ * @since 1.5
+ * @global int $timestart Seconds and Microseconds added together from when timer_start() is called
+ * @global int $timeend  Seconds and Microseconds added together from when function is called
+ *
+ * @param int $display Use '0' or null to not echo anything and 1 to echo the total time
+ * @param int $precision The amount of digits from the right of the decimal to display. Default is 3.
+ * @return float The "second.microsecond" finished time calculation
+ */
 function timer_stop($display = 0, $precision = 3) { //if called like timer_stop(1), will echo $timetotal
 	global $timestart, $timeend;
 	$mtime = microtime();
@@ -104,15 +163,31 @@ function timer_stop($display = 0, $precision = 3) { //if called like timer_stop(
 if ( defined('WP_CACHE') )
 	@include ABSPATH . 'wp-content/advanced-cache.php';
 
+/**
+ * Stores the location of the WordPress directory of functions, classes, and core content.
+ *
+ * @since 1.5
+ */
 define('WPINC', 'wp-includes');
 
 if ( !defined('LANGDIR') ) {
+	/**
+	 * Stores the location of the language directory. First looks for language folder in wp-content 
+	 * and uses that folder if it exists. Or it uses the "languages" folder in WPINC.
+	 *
+	 * @since 1.5
+	 */
 	if ( file_exists(ABSPATH . 'wp-content/languages') && @is_dir(ABSPATH . 'wp-content/languages') )
 		define('LANGDIR', 'wp-content/languages'); // no leading slash, no trailing slash
 	else
 		define('LANGDIR', WPINC . '/languages'); // no leading slash, no trailing slash
 }
 
+/**
+ * Allows for the plugins directory to be moved from the default location.
+ *
+ * @since 2.1
+ */
 if ( !defined('PLUGINDIR') )
 	define('PLUGINDIR', 'wp-content/plugins'); // no leading slash, no trailing slash
 
@@ -180,23 +255,61 @@ function timer_stop($display = 0, $precision = 3) { //if called like timer_stop(
 require (ABSPATH . WPINC . '/canonical.php');
 
 if (strpos($_SERVER['PHP_SELF'], 'install.php') === false) {
-    // Used to guarantee unique hash cookies
-    $cookiehash = md5(get_option('siteurl'));
+	// Used to guarantee unique hash cookies
+	$cookiehash = md5(get_option('siteurl'));
+	/**
+	 * Used to guarantee unique hash cookies
+	 * @since 1.5
+	 */
 	define('COOKIEHASH', $cookiehash);
 }
 
+/**
+ * It is possible to define this in wp-config.php
+ * @since 2.0
+ */
 if ( !defined('USER_COOKIE') )
 	define('USER_COOKIE', 'wordpressuser_' . COOKIEHASH);
+
+/**
+ * It is possible to define this in wp-config.php
+ * @since 2.0
+ */
 if ( !defined('PASS_COOKIE') )
 	define('PASS_COOKIE', 'wordpresspass_' . COOKIEHASH);
+
+/**
+ * It is possible to define this in wp-config.php
+ * @since 2.4
+ */
 if ( !defined('AUTH_COOKIE') )
 	define('AUTH_COOKIE', 'wordpress_' . COOKIEHASH);
+
+/**
+ * It is possible to define this in wp-config.php
+ * @since 2.3
+ */
 if ( !defined('TEST_COOKIE') )
 	define('TEST_COOKIE', 'wordpress_test_cookie');
+
+/**
+ * It is possible to define this in wp-config.php
+ * @since 2.0
+ */
 if ( !defined('COOKIEPATH') )
 	define('COOKIEPATH', preg_replace('|https?://[^/]+|i', '', get_option('home') . '/' ) );
+
+/**
+ * It is possible to define this in wp-config.php
+ * @since 2.0
+ */
 if ( !defined('SITECOOKIEPATH') )
 	define('SITECOOKIEPATH', preg_replace('|https?://[^/]+|i', '', get_option('siteurl') . '/' ) );
+
+/**
+ * It is possible to define this in wp-config.php
+ * @since 2.0
+ */
 if ( !defined('COOKIE_DOMAIN') )
 	define('COOKIE_DOMAIN', false);
 
@@ -240,12 +353,46 @@ function timer_stop($display = 0, $precision = 3) { //if called like timer_stop(
 
 do_action('sanitize_comment_cookies');
 
+/**
+ * WordPress Query object
+ * @global object $wp_the_query
+ * @since 2.0
+ */
 $wp_the_query =& new WP_Query();
+
+/**
+ * Holds the reference to @see $wp_the_query
+ * Use this global for WordPress queries
+ * @global object $wp_query
+ * @since 2.0
+ */
 $wp_query     =& $wp_the_query;
+
+/**
+ * Holds the WordPress Rewrite object for creating pretty URLs
+ * @global object $wp_rewrite
+ * @since 2.0
+ */
 $wp_rewrite   =& new WP_Rewrite();
+
+/**
+ * WordPress Object
+ * @global object $wp
+ * @since 2.0
+ */
 $wp           =& new WP();
 
+
+/**
+ * Web Path to the current active template directory
+ * @since 1.5
+ */
 define('TEMPLATEPATH', get_template_directory());
+
+/**
+ * Web Path to the current active template stylesheet directory
+ * @since 2.1
+ */
 define('STYLESHEETPATH', get_stylesheet_directory());
 
 // Load the default text localization domain.
@@ -259,6 +406,11 @@ function timer_stop($display = 0, $precision = 3) { //if called like timer_stop(
 // Pull in locale data after loading text domain.
 require_once(ABSPATH . WPINC . '/locale.php');
 
+/**
+ * WordPress Locale object for loading locale domain date and various strings.
+ * @global object $wp_locale
+ * @since 2.1
+ */
 $wp_locale =& new WP_Locale();
 
 // Load functions for active theme.
@@ -267,6 +419,13 @@ function timer_stop($display = 0, $precision = 3) { //if called like timer_stop(
 if ( file_exists(TEMPLATEPATH . '/functions.php') )
 	include(TEMPLATEPATH . '/functions.php');
 
+/**
+ * Runs just before PHP shuts down execution.
+ *
+ * @access private
+ * @package WordPress
+ * @since 1.5
+ */
 function shutdown_action_hook() {
 	do_action('shutdown');
 	wp_cache_close();