From 175c2b6fb1abc2d118e632f8f4c3021c53cf5671 Mon Sep 17 00:00:00 2001
From: ryan <ryan@1a063a9b-81f0-0310-95a4-ce76da25c4cd>
Date: Mon, 11 Aug 2008 20:26:31 +0000
Subject: [PATCH] WP-Admin File Level Inline Documentation from santosj. see
 #7496

git-svn-id: http://svn.automattic.com/wordpress/trunk@8618 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/admin-ajax.php      | 14 ++++++-
 wp-admin/admin-footer.php    |  8 ++++
 wp-admin/admin-functions.php | 15 +++++++-
 wp-admin/admin-header.php    |  7 ++++
 wp-admin/admin-post.php      | 10 ++++-
 wp-admin/admin.php           | 14 ++++++-
 wp-admin/async-upload.php    | 12 +++---
 wp-admin/categories.php      |  8 ++++
 wp-admin/comment.php         | 17 ++++++++-
 wp-admin/custom-header.php   |  2 +-
 wp-admin/export.php          | 12 +++++-
 wp-admin/gears-manifest.php  | 71 ++++++++++++++++++++++++++++++++++++
 wp-admin/import.php          |  8 ++++
 wp-admin/includes/admin.php  | 36 +++++++++++++++++-
 wp-admin/index-extra.php     | 14 ++++++-
 wp-admin/index.php           | 13 +++++++
 16 files changed, 245 insertions(+), 16 deletions(-)

diff --git a/wp-admin/admin-ajax.php b/wp-admin/admin-ajax.php
index 5e9a44df4..1d76df7e5 100644
--- a/wp-admin/admin-ajax.php
+++ b/wp-admin/admin-ajax.php
@@ -1,4 +1,16 @@
 <?php
+/**
+ * WordPress AJAX Process Execution.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/**
+ * Executing AJAX process.
+ *
+ * @since unknown
+ */
 define('DOING_AJAX', true);
 
 require_once('../wp-load.php');
@@ -641,4 +653,4 @@ default :
 	die('0');
 	break;
 endswitch;
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/admin-footer.php b/wp-admin/admin-footer.php
index d5f129f3b..ea7e69a8e 100644
--- a/wp-admin/admin-footer.php
+++ b/wp-admin/admin-footer.php
@@ -1,3 +1,11 @@
+<?php
+/**
+ * WordPress Administration Template Footer
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+?>
 </div><!-- wpbody -->
 </div><!-- wpcontent -->
 </div><!-- wpwrap -->
diff --git a/wp-admin/admin-functions.php b/wp-admin/admin-functions.php
index 4a0d327b3..b8c84fdad 100644
--- a/wp-admin/admin-functions.php
+++ b/wp-admin/admin-functions.php
@@ -1,5 +1,16 @@
 <?php
-// Deprecated.  Use includes/admin.php.
+/**
+ * Administration Functions
+ *
+ * This file is deprecated, use 'wp-admin/includes/admin.php' instead.
+ *
+ * @deprecated 2.5
+ * @package WordPress
+ * @subpackage Administration
+ */
+
 _deprecated_file( basename(__FILE__), '2.5', 'wp-admin/includes/admin.php' );
+
+/** WordPress Administration API: Includes all Administration functions. */
 require_once(ABSPATH . 'wp-admin/includes/admin.php');
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/admin-header.php b/wp-admin/admin-header.php
index f24ca4119..81b5f6d3e 100644
--- a/wp-admin/admin-header.php
+++ b/wp-admin/admin-header.php
@@ -1,4 +1,11 @@
 <?php
+/**
+ * WordPress Administration Template Header
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
 @header('Content-Type: ' . get_option('html_type') . '; charset=' . get_option('blog_charset'));
 if (!isset($_GET["page"])) require_once('admin.php');
 if ( $editing ) {
diff --git a/wp-admin/admin-post.php b/wp-admin/admin-post.php
index f45fc62ec..55c7d9f36 100644
--- a/wp-admin/admin-post.php
+++ b/wp-admin/admin-post.php
@@ -1,5 +1,13 @@
 <?php
-define('WP_ADMIN', TRUE);
+/**
+ * WordPress Administration Generic POST Handler.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** We are located in WordPress Administration Panels */
+define('WP_ADMIN', true);
 
 if ( defined('ABSPATH') )
 	require_once(ABSPATH . 'wp-load.php');
diff --git a/wp-admin/admin.php b/wp-admin/admin.php
index 20ff3693f..c9b5a0f3e 100644
--- a/wp-admin/admin.php
+++ b/wp-admin/admin.php
@@ -1,4 +1,16 @@
 <?php
+/**
+ * WordPress Administration Bootstrap
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/**
+ * In WordPress Administration Panels
+ *
+ * @since unknown
+ */
 define('WP_ADMIN', TRUE);
 
 if ( defined('ABSPATH') )
@@ -116,4 +128,4 @@ if (isset($plugin_page)) {
 if ( !empty($_REQUEST['action']) )
 	do_action('admin_action_' . $_REQUEST['action']);
 
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/async-upload.php b/wp-admin/async-upload.php
index 68e355e56..dd85c73f0 100644
--- a/wp-admin/async-upload.php
+++ b/wp-admin/async-upload.php
@@ -1,8 +1,10 @@
 <?php
-
-/* This accepts file uploads from swfupload or other asynchronous upload methods.
-
-*/
+/**
+ * Accepts file uploads from swfupload or other asynchronous upload methods.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
 if ( defined('ABSPATH') )
 	require_once(ABSPATH . 'wp-load.php');
@@ -46,4 +48,4 @@ else {
 	echo apply_filters("async_upload_{$type}", $id);
 }
 
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/categories.php b/wp-admin/categories.php
index d2e8fb372..a1e6c91b1 100644
--- a/wp-admin/categories.php
+++ b/wp-admin/categories.php
@@ -1,4 +1,12 @@
 <?php
+/**
+ * Categories Management Panel
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** Load WordPress Bootstrap */
 require_once('admin.php');
 
 $title = __('Categories');
diff --git a/wp-admin/comment.php b/wp-admin/comment.php
index d1e394ea9..73cfe4c80 100644
--- a/wp-admin/comment.php
+++ b/wp-admin/comment.php
@@ -1,4 +1,12 @@
 <?php
+/**
+ * Comment Management Panel
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** Load WordPress Bootstrap */
 require_once('admin.php');
 
 $parent_file = 'edit-comments.php';
@@ -9,7 +17,12 @@ wp_reset_vars( array('action') );
 if ( isset( $_POST['deletecomment'] ) )
 	$action = 'deletecomment';
 
-function comment_footer_die( $msg ) {  // $msg is assumed to contain HTML and be sanitized
+/**
+ * Display error message at bottom of comments.
+ *
+ * @param string $msg Error Message. Assumed to contain HTML and be sanitized.
+ */
+function comment_footer_die( $msg ) {  // 
 	echo "<div class='wrap'><p>$msg</p></div>";
 	include('admin-footer.php');
 	die;
@@ -225,4 +238,4 @@ default:
 
 include('admin-footer.php');
 
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/custom-header.php b/wp-admin/custom-header.php
index c35200b6c..c0e8c54bb 100644
--- a/wp-admin/custom-header.php
+++ b/wp-admin/custom-header.php
@@ -361,4 +361,4 @@ Event.observe( window, 'load', hide_text );
 	}
 
 }
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/export.php b/wp-admin/export.php
index 08a0b2571..416e12a85 100644
--- a/wp-admin/export.php
+++ b/wp-admin/export.php
@@ -1,5 +1,15 @@
 <?php
+/**
+ * WordPress Export Administration Panel
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** Load WordPress Bootstrap */
 require_once ('admin.php');
+
+/** Load WordPress export API */
 require_once('includes/export.php');
 $title = __('Export');
 $parent_file = 'edit.php';
@@ -47,4 +57,4 @@ foreach ( $authors as $id ) {
 
 
 include ('admin-footer.php');
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/gears-manifest.php b/wp-admin/gears-manifest.php
index 01aa7ce1f..6dc92afab 100644
--- a/wp-admin/gears-manifest.php
+++ b/wp-admin/gears-manifest.php
@@ -1,20 +1,91 @@
 <?php
+/**
+ * Define Gears manifest for Google Gears storage.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/** Set ABSPATH for execution */
 define( 'ABSPATH', dirname(dirname(__FILE__)) );
 define( 'WPINC', '/wp-includes' );
 
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function __() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function add_filter() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function attribute_escape() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function apply_filters() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function get_option() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function is_lighttpd_before_150() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function add_action() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function do_action_ref_array() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function get_bloginfo() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function is_admin() {return true;}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function site_url() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function admin_url() {}
+
+/**
+ * @package WordPress
+ * @subpackage Dummy
+ */
 function wp_guess_url() {}
 
 require(ABSPATH . '/wp-includes/script-loader.php');
diff --git a/wp-admin/import.php b/wp-admin/import.php
index 45ca450fd..0baff9ff9 100644
--- a/wp-admin/import.php
+++ b/wp-admin/import.php
@@ -1,4 +1,12 @@
 <?php
+/**
+ * Import WordPress Administration Panel
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** Load WordPress Bootstrap */
 require_once ('admin.php');
 $title = __('Import');
 $parent_file = 'edit.php';
diff --git a/wp-admin/includes/admin.php b/wp-admin/includes/admin.php
index 9bd251368..a75a19934 100644
--- a/wp-admin/includes/admin.php
+++ b/wp-admin/includes/admin.php
@@ -1,20 +1,54 @@
 <?php
+/**
+ * Includes all of the WordPress Administration API files.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/** WordPress Bookmark Administration API */
 require_once(ABSPATH . 'wp-admin/includes/bookmark.php');
+
+/** WordPress Comment Administration API */
 require_once(ABSPATH . 'wp-admin/includes/comment.php');
+
+/** WordPress Administration File API */
 require_once(ABSPATH . 'wp-admin/includes/file.php');
+
+/** WordPress Image Administration API */
 require_once(ABSPATH . 'wp-admin/includes/image.php');
+
+/** WordPress Media Administration API */
 require_once(ABSPATH . 'wp-admin/includes/media.php');
+
+/** WordPress Import Administration API */
 require_once(ABSPATH . 'wp-admin/includes/import.php');
+
+/** WordPress Misc Administration API */
 require_once(ABSPATH . 'wp-admin/includes/misc.php');
+
+/** WordPress Plugin Administration API */
 require_once(ABSPATH . 'wp-admin/includes/plugin.php');
+
+/** WordPress Post Administration API */
 require_once(ABSPATH . 'wp-admin/includes/post.php');
+
+/** WordPress Taxonomy Administration API */
 require_once(ABSPATH . 'wp-admin/includes/taxonomy.php');
+
+/** WordPress Template Administration API */
 require_once(ABSPATH . 'wp-admin/includes/template.php');
+
+/** WordPress Theme Administration API */
 require_once(ABSPATH . 'wp-admin/includes/theme.php');
+
+/** WordPress User Administration API */
 require_once(ABSPATH . 'wp-admin/includes/user.php');
+
+/** WordPress Update Administration API */
 require_once(ABSPATH . 'wp-admin/includes/update.php');
 
+/** WordPress Registration API */
 require_once(ABSPATH . WPINC . '/registration.php');
 
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/index-extra.php b/wp-admin/index-extra.php
index 3b77d104b..cd244106e 100644
--- a/wp-admin/index-extra.php
+++ b/wp-admin/index-extra.php
@@ -1,6 +1,18 @@
 <?php
+/**
+ * Handle default dashboard widgets options AJAX.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** Load WordPress Bootstrap */
 require_once('admin.php');
+
+/** Load WordPress Administration Dashboard API */
 require( 'includes/dashboard.php' );
+
+/** Load Magpie RSS API or custom RSS API */
 require_once (ABSPATH . WPINC . '/rss.php');
 
 @header('Content-Type: ' . get_option('html_type') . '; charset=' . get_option('blog_charset'));
@@ -25,4 +37,4 @@ case 'plugins' :
 
 }
 
-?>
+?>
\ No newline at end of file
diff --git a/wp-admin/index.php b/wp-admin/index.php
index 018f5ef31..5bec6946c 100644
--- a/wp-admin/index.php
+++ b/wp-admin/index.php
@@ -1,11 +1,24 @@
 <?php
+/**
+ * Dashboard Administration Panel
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/** Load WordPress Bootstrap */
 require_once('admin.php');
 
+/** Load WordPress dashboard API */
 require_once(ABSPATH . 'wp-admin/includes/dashboard.php');
 
 wp_dashboard_setup();
 
+/**
+ * Display dashboard widget custom JavaScript.
+ *
+ * @since unknown
+ */
 function index_js() {
 ?>
 <script type="text/javascript">