File file level phpdoc from jacobsantos. see #7037

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

index.php

@@ -1,5 +1,19 @@
 <?php
-/* Short and sweet */
+/**
+ * Front to the WordPress application. Most of WordPress is loaded through this
+ * file. This file doesn't do anything, but loads the file which does and tells
+ * WordPress to load the theme.
+ *
+ * @package WordPress
+ */
+
+/**
+ * Tells WordPress to load the WordPress theme and output it.
+ *
+ * @var bool
+ */
 define('WP_USE_THEMES', true);
+
+/** Loads the WordPress Environment and Template */
 require('./wp-blog-header.php');
 ?>

wp-app.php

@@ -1,26 +1,60 @@
 <?php
-/*
- * wp-app.php - Atom Publishing Protocol support for WordPress
- * Original code by: Elias Torres, http://torrez.us/archives/2006/08/31/491/
- * Modified by: Dougal Campbell, http://dougal.gunters.org/
+/**
+ * Atom Publishing Protocol support for WordPress
  *
- * Version: 1.0.5-dc
+ * @author Original by Elias Torres <http://torrez.us/archives/2006/08/31/491/>
+ * @author Modified by Dougal Campbell <http://dougal.gunters.org/>
+ * @version 1.0.5-dc
  */
 
+/**
+ * WordPress is handling an Atom Publishing Protocol request.
+ *
+ * @var bool
+ */
 define('APP_REQUEST', true);
 
+/** Set up WordPress environment */
 require_once('./wp-load.php');
+
+/** Post Template API */
 require_once(ABSPATH . WPINC . '/post-template.php');
+
+/** Atom Publishing Protocol Class */
 require_once(ABSPATH . WPINC . '/atomlib.php');
+
+/** Feed Handling API */
 require_once(ABSPATH . WPINC . '/feed.php');
 
 $_SERVER['PATH_INFO'] = preg_replace( '/.*\/wp-app\.php/', '', $_SERVER['REQUEST_URI'] );
 
+/**
+ * Whether to enable Atom Publishing Protocol Logging.
+ *
+ * @name app_logging
+ * @var int|bool
+ */
 $app_logging = 0;
 
-// TODO: Should be an option somewhere
+/**
+ * Whether to always authenticate user. Permanently set to true.
+ *
+ * @name always_authenticate
+ * @var int|bool
+ * @todo Should be an option somewhere
+ */
 $always_authenticate = 1;
 
+/**
+ * log_app() - Writes logging info to a file.
+ *
+ * @uses $app_logging
+ * @package WordPress
+ * @subpackage Logging
+ *
+ * @param string $label Type of logging
+ * @param string $msg Information describing logging reason.
+ */
 function log_app($label,$msg) {
 	global $app_logging;
 	if ($app_logging) {
@@ -32,6 +66,18 @@ function log_app($label,$msg) {
 }
 
 if ( !function_exists('wp_set_current_user') ) :
+/**
+ * wp_set_current_user() - Sets the current WordPress User
+ *
+ * Pluggable function which is also found in pluggable.php.
+ *
+ * @see wp-includes/pluggable.php Documentation for this function.
+ * @uses $current_user Global of current user to test whether $id is the same.
+ *
+ * @param int $id The user's ID
+ * @param string $name Optional. The username of the user.
+ * @return WP_User Current user's User object
+ */
 function wp_set_current_user($id, $name = '') {
 	global $current_user;
 
@@ -44,13 +90,26 @@ function wp_set_current_user($id, $name = '') {
 }
 endif;
 
+/**
+ * wa_posts_where_include_drafts_filter() - Filter to add more post statuses
+ *
+ * @param string $where SQL statement to filter
+ * @return string Filtered SQL statement with added post_status for where clause
+ */
 function wa_posts_where_include_drafts_filter($where) {
-        $where = str_replace("post_status = 'publish'","post_status = 'publish' OR post_status = 'future' OR post_status = 'draft' OR post_status = 'inherit'", $where);
-        return $where;
+	$where = str_replace("post_status = 'publish'","post_status = 'publish' OR post_status = 'future' OR post_status = 'draft' OR post_status = 'inherit'", $where);
+	return $where;
 
 }
 add_filter('posts_where', 'wa_posts_where_include_drafts_filter');
 
+/**
+ * @internal
+ * Left undocumented to work on later. If you want to finish, then please do so.
+ *
+ * @package WordPress
+ * @subpackage Publishing
+ */
 class AtomServer {
 
 	var $ATOM_CONTENT_TYPE = 'application/atom+xml';
@@ -170,9 +229,9 @@ class AtomServer {
 		$entries_url = attribute_escape($this->get_entries_url());
 		$categories_url = attribute_escape($this->get_categories_url());
 		$media_url = attribute_escape($this->get_attachments_url());
-                foreach ($this->media_content_types as $med) {
-                  $accepted_media_types = $accepted_media_types . "<accept>" . $med . "</accept>";
-                }
+		foreach ($this->media_content_types as $med) {
+			$accepted_media_types = $accepted_media_types . "<accept>" . $med . "</accept>";
+		}
 		$atom_prefix="atom";
 		$atom_blogname=get_bloginfo('name');
 		$service_doc = <<<EOD

wp-atom.php

@@ -1,4 +1,15 @@
 <?php
+/**
+ * Outputs the Atom feed XML format using the feed-atom.php file in wp-includes
+ * folder. This file only sets the feed format and includes the feed-atom.php.
+ *
+ * This file is no longer used in WordPress and while it is not deprecated now.
+ * This file will most likely be deprecated or removed in a later version.
+ *
+ * The link for the atom feed is /index.php?feed=atom with permalinks off.
+ *
+ * @package WordPress
+ */
 
 if (empty($wp)) {
 	require_once('./wp-load.php');

wp-blog-header.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Loads the WordPress environment and template.
+ *
+ * @package WordPress
+ */
 
 if ( !isset($wp_did_header) ) {
 

wp-comments-post.php

@@ -1,10 +1,18 @@
 <?php
+/**
+ * Handles Comment Post to WordPress and prevents duplicate comment posting.
+ *
+ * @package @WordPress
+ */
+
 if ( 'POST' != $_SERVER['REQUEST_METHOD'] ) {
 	header('Allow: POST');
 	header('HTTP/1.1 405 Method Not Allowed');
 	header('Content-Type: text/plain');
 	exit;
 }
+
+/** Sets up the WordPress Environment. */
 require( dirname(__FILE__) . '/wp-load.php' );
 
 nocache_headers();

wp-commentsrss2.php

@@ -1,4 +1,17 @@
 <?php
+/**
+ * Outputs the RSS2 XML format comment feed using the feed-rss2.php file in
+ * wp-includes folder. This file only sets the feed format and includes the
+ * feed-rss2-comments.php.
+ *
+ * This file is no longer used in WordPress and while it is not deprecated now.
+ * This file will most likely be deprecated or removed in a later version.
+ *
+ * The link for the rss2 comment feed is /index.php?feed=rss2&withcomments=1
+ * with permalinks off.
+ *
+ * @package WordPress
+ */
 
 if (empty($wp)) {
 	require_once('./wp-load.php');

wp-cron.php

@@ -1,6 +1,23 @@
 <?php
+/**
+ * WordPress Cron Implementation for hosts, which do not offer CRON or for which
+ * the user has not setup a CRON job pointing to this file.
+ *
+ * The HTTP request to this file will not slow down the visitor who happens to
+ * visit when the cron job is needed to run.
+ *
+ * @package WordPress
+ */
+
 ignore_user_abort(true);
-define('DOING_CRON', TRUE);
+
+/**
+ * Tell WordPress we are doing the CRON task.
+ *
+ * @var bool
+ */
+define('DOING_CRON', true);
+/** Setup WordPress environment */
 require_once('./wp-load.php');
 
 if ( $_GET['check'] != wp_hash('187425') )
@@ -15,6 +32,7 @@ $crons = _get_cron_array();
 $keys = array_keys($crons);
 if (!is_array($crons) || $keys[0] > time())
 	return;
+
 foreach ($crons as $timestamp => $cronhooks) {
 	if ($timestamp > time()) break;
 	foreach ($cronhooks as $hook => $keys) {

wp-feed.php

@@ -1,4 +1,18 @@
 <?php
+/**
+ * Outputs the RSS2 feed XML format. This file is a shortcut or compatibility
+ * layer for easily finding the RSS feed for the site. It loads WordPress using
+ * the wp-blog-header.php file and running do_feed() function.
+ *
+ * @see do_feed() Used to display the RSS2 feed
+ *
+ * This file is no longer used in WordPress and while it is not deprecated now.
+ * This file will most likely be deprecated or removed in a later version.
+ *
+ * The link for the rss2 feed is /index.php?feed=rss2 with permalinks off.
+ *
+ * @package WordPress
+ */
 
 if (empty($doing_rss)) {
 	$doing_rss = 1;

wp-links-opml.php

@@ -1,4 +1,16 @@
 <?php
+/**
+ * Outputs the OPML XML format for getting the links defined in the link
+ * administration. This can be used to export links from one blog over to
+ * another. Links aren't exported by the WordPress export, so this file handles
+ * that.
+ *
+ * This file is not added by default to WordPress theme pages when outputting
+ * feed links. It will have to be added manually for browsers and users to pick
+ * up that this file exists.
+ *
+ * @package WordPress
+ */
 
 if (empty($wp)) {
 	require_once('./wp-load.php');

wp-load.php

@@ -1,16 +1,32 @@
 <?php
+/**
+ * Bootstrap file for setting the ABSPATH constant
+ * and loading the wp-config.php file. The wp-config.php
+ * file will then load the wp-settings.php file, which
+ * will then set up the WordPress environment.
+ *
+ * If the wp-config.php file is not found then an error
+ * will be displayed asking the visitor to set up the
+ * wp-config.php file.
+ *
+ * Also made to work in the wp-admin/ folder, because it
+ * will look in the parent directory if the file is not
+ * found in the current directory.
+ *
+ * @package WordPress
+ */
 
-// Define ABSPATH as this files directory
+/** Define ABSPATH as this files directory */
 define( 'ABSPATH', dirname(__FILE__) . '/' );
 
 if ( file_exists( ABSPATH . 'wp-config.php') ) {
 
-	// The config file resides in ABSPATH
+	/** The config file resides in ABSPATH */
 	require_once( ABSPATH . 'wp-config.php' );
 
 } elseif ( file_exists( dirname(ABSPATH) . '/wp-config.php' ) ) {
 
-	// The config file resides one level below ABSPATH
+	/** The config file resides one level below ABSPATH */
 	require_once( dirname(ABSPATH) . '/wp-config.php' );
 
 } else {

wp-login.php

@@ -1,7 +1,29 @@
 <?php
+/**
+ *
+ * @package WordPress
+ */
+
+/** Make sure that the WordPress bootstrap has ran before continuing. */
 require( dirname(__FILE__) . '/wp-load.php' );
 
-// Rather than duplicating this HTML all over the place, we'll stick it in function
+/**
+ * login_header() - Outputs the header for the login page
+ *
+ * @package WordPress
+ * @uses do_action() Calls the 'login_head' for outputting HTML in the Login
+ *		header.
+ * @uses apply_filters() Calls 'login_headerurl' for the top login link.
+ * @uses apply_filters() Calls 'login_headertitle' for the top login title.
+ * @uses apply_filters() Calls 'login_message' on the message to display in the
+ *		header.
+ * @uses $error The error global, which is checked for displaying errors.
+ *
+ * @param string $title Optional. WordPress Login Page title to display in
+ *		<title/> element.
+ * @param string $message Optional. Message to display in header.
+ * @param WP_Error $wp_error Optional. WordPress Error Object
+ */
 function login_header($title = 'Login', $message = '', $wp_error = '') {
 	global $error;
 
@@ -56,6 +78,15 @@ function login_header($title = 'Login', $message = '', $wp_error = '') {
 	}
 } // End of login_header()
 
+/**
+ * retrieve_password() - Handles sending password retrieval email to user
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @uses $wpdb WordPress Database object
+ *
+ * @return bool|WP_Error True: when finish. WP_Error on error
+ */
 function retrieve_password() {
 	global $wpdb;
 
@@ -110,6 +141,16 @@ function retrieve_password() {
 	return true;
 }
 
+/**
+ * reset_password() - Handles resetting the user's password
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @uses $wpdb WordPress Database object
+ *
+ * @param string $key Hash to validate sending user's password
+ * @return bool|WP_Error
+ */
 function reset_password($key) {
 	global $wpdb;
 
@@ -144,6 +185,15 @@ function reset_password($key) {
 	return true;
 }
 
+/**
+ * register_new_user() - Handles registering a new user
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @param string $user_login User's username for logging in
+ * @param string $user_email User's email address to send password and add
+ * @return int|WP_Error Either user's ID or error on failure.
+ */
 function register_new_user($user_login, $user_email) {
 	$errors = new WP_Error();
 

wp-mail.php

@@ -1,8 +1,18 @@
 <?php
+/**
+ * Gets the email message from the user's mailbox to add as
+ * a WordPress post. Will only run if this is setup and enabled.
+ *
+ * @package WordPress
+ */
+
+/** Make sure that the WordPress bootstrap has ran before continuing. */
 require(dirname(__FILE__) . '/wp-load.php');
 
+/** Get the POP3 class for which to access the mailbox. */
 require_once(ABSPATH.WPINC.'/class-pop3.php');
 
+// WTF is this? Use constants instead.
 error_reporting(2037);
 
 $time_difference = get_option('gmt_offset') * 3600;

wp-pass.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Creates the password cookie and redirects back to where the
+ * visitor was before.
+ *
+ * @package WordPress
+ */
+
+/** Make sure that the WordPress bootstrap has ran before continuing. */
 require( dirname(__FILE__) . '/wp-load.php');
 
 if ( get_magic_quotes_gpc() )

wp-rdf.php

@@ -1,4 +1,17 @@
-<?php /* RDF 1.0 generator, original version by garym@teledyn.com */
+<?php
+/**
+ * Outputs the RDF feed using the feed-rdf.php
+ * file in wp-includes folder.
+ *
+ * This file only sets the feed format and includes the
+ * feed-rdf.php.
+ *
+ * This file is no longer used in WordPress and while it is
+ * not deprecated now. This file will most likely be
+ * deprecated or removed in a later version.
+ *
+ * @package WordPress
+ */
 
 if (empty($wp)) {
 	require_once('./wp-load.php');

wp-register.php

@@ -1,7 +1,13 @@
 <?php
-
-# This file is deprecated, but you shouldn't have been linking to it directly anyway :P
-# Use wp_register() to create a registration link instead, it's much better ;)
+/**
+ * Used to be the page which displayed the registration form.
+ *
+ * This file is no longer used in WordPress and is
+ * deprecated.
+ *
+ * @package WordPress
+ * @deprecated Use wp_register() to create a registration link instead
+ */
 
 require('./wp-load.php');
 wp_redirect('wp-login.php?action=register');

wp-rss.php

@@ -1,4 +1,17 @@
 <?php
+/**
+ * Outputs the RSS feed RDF format using the feed-rss.php
+ * file in wp-includes folder.
+ *
+ * This file only sets the feed format and includes the
+ * feed-rss.php.
+ *
+ * This file is no longer used in WordPress and while it is
+ * not deprecated now. This file will most likely be
+ * deprecated or removed in a later version.
+ *
+ * @package WordPress
+ */
 
 if (empty($wp)) {
 	require_once('./wp-load.php');

wp-rss2.php

@@ -1,4 +1,15 @@
 <?php
+/**
+ * Outputs the RSS2 feed XML format using the feed-rss2.php file in wp-includes
+ * folder. This file only sets the feed format and includes the feed-rss2.php.
+ *
+ * This file is no longer used in WordPress and while it is not deprecated now.
+ * This file will most likely be deprecated or removed in a later version.
+ *
+ * The link for the rss2 feed is /index.php?feed=rss2 with permalinks off.
+ *
+ * @package WordPress
+ */
 
 if (empty($wp)) {
 	require_once('./wp-load.php');

wp-trackback.php

@@ -1,10 +1,21 @@
 <?php
+/**
+ * Handle Trackbacks and Pingbacks sent to WordPress
+ *
+ * @package WordPress
+ */
 
 if (empty($wp)) {
 	require_once('./wp-load.php');
 	wp('tb=1');
 }
 
+/**
+ * trackback_response() - Respond with error or success XML message
+ *
+ * @param int|bool $error Whether there was an error or not
+ * @param string $error_message Error message if an error occurred
+ */
 function trackback_response($error = 0, $error_message = '') {
 	header('Content-Type: text/xml; charset=' . get_option('blog_charset') );
 	if ($error) {

xmlrpc.php

@@ -1,5 +1,16 @@
 <?php
+/**
+ * XML-RPC protocol support for WordPress
+ *
+ * @license GPL v2 <./license.txt>
+ * @package WordPress
+ */
 
+/**
+ * Whether this is a XMLRPC Request
+ *
+ * @var bool
+ */
 define('XMLRPC_REQUEST', true);
 
 // Some browser-embedded clients send cookies. We don't want them.
@@ -11,10 +22,11 @@ if ( !isset( $HTTP_RAW_POST_DATA ) ) {
 	$HTTP_RAW_POST_DATA = file_get_contents( 'php://input' );
 }
 
-# fix for mozBlog and other cases where '<?xml' isn't on the very first line
+// fix for mozBlog and other cases where '<?xml' isn't on the very first line
 if ( isset($HTTP_RAW_POST_DATA) )
 	$HTTP_RAW_POST_DATA = trim($HTTP_RAW_POST_DATA);
 
+/** Include the bootstrap for setting up WordPress environment */
 include('./wp-load.php');
 
 if ( isset( $_GET['rsd'] ) ) { // http://archipelago.phrasewise.com/rsd
@@ -45,10 +57,32 @@ include_once(ABSPATH . WPINC . '/class-IXR.php');
 // Turn off all warnings and errors.
 // error_reporting(0);
 
-$post_default_title = ""; // posts submitted via the xmlrpc interface get that title
+/**
+ * Posts submitted via the xmlrpc interface get that title
+ * @name post_default_title
+ * @var string
+ */
+$post_default_title = "";
 
+/**
+ * Whether to enable XMLRPC Logging.
+ *
+ * @name xmlrpc_logging
+ * @var int|bool
+ */
 $xmlrpc_logging = 0;
 
+/**
+ * logIO() - Writes logging info to a file.
+ *
+ * @uses $xmlrpc_logging
+ * @package WordPress
+ * @subpackage Logging
+ *
+ * @param string $io Whether input or output
+ * @param string $msg Information describing logging reason.
+ * @return bool Always return true
+ */
 function logIO($io,$msg) {
 	global $xmlrpc_logging;
 	if ($xmlrpc_logging) {
@@ -62,8 +96,15 @@ function logIO($io,$msg) {
 }
 
 if ( isset($HTTP_RAW_POST_DATA) )
-  logIO("I", $HTTP_RAW_POST_DATA);
+	logIO("I", $HTTP_RAW_POST_DATA);
 
+/**
+ * @internal
+ * Left undocumented to work on later. If you want to finish, then please do so.
+ *
+ * @package WordPress
+ * @subpackage Publishing
+ */
 class wp_xmlrpc_server extends IXR_Server {
 
 	function wp_xmlrpc_server() {