Improve file headers, class doc blocks, etc

aijazsiddique · Apr 9, 2015 · d73089b · d73089b
1 parent 23d7ea1
commit d73089b
Show file tree

Hide file tree

Showing 14 changed files with 152 additions and 34 deletions.
diff --git a/bootstrap.php b/bootstrap.php
@@ -1,4 +1,13 @@
 <?php
+/**
+ * Bootstraps the CMB process
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
+ */
 
 /**
  * Fires when CMB2 is included/loaded

diff --git a/example-functions.php b/example-functions.php
@@ -6,7 +6,7 @@
  * http://nacin.com/2010/05/11/in-wordpress-prefix-everything/
  *
  * @category YourThemeOrPlugin
- * @package  Metaboxes
+ * @package  CMB2_Metabox_Configuration_Demo
  * @license  http://www.opensource.org/licenses/gpl-license.php GPL v2.0 (or later)
  * @link     https://github.com/WebDevStudios/CMB2
  */

diff --git a/includes/CMB2.php b/includes/CMB2.php
@@ -1,6 +1,12 @@
 <?php
 /**
- * Create meta boxes
+ * CMB2 - The core metabox object
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
  *
  * @property-read string $cmb_id
  * @property-read array $meta_box
@@ -20,11 +26,11 @@ class CMB2 {
 	 * @var   array
 	 * @since 0.9.0
 	 */
-	protected $meta_box;
+	protected $meta_box = array();
 
 	/**
 	 * Object ID for metabox meta retrieving/saving
-	 * @var   int
+	 * @var   mixed
 	 * @since 1.0.0
 	 */
 	protected $object_id = 0;

diff --git a/includes/CMB2_Ajax.php b/includes/CMB2_Ajax.php
@@ -5,18 +5,21 @@
  * (i.e. a lot of work to get oEmbeds to work with non-post objects)
  *
  * @since  0.9.5
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
  */
 class CMB2_Ajax {
 
-
 	// Whether to hijack the oembed cache system
 	protected $hijack      = false;
 	protected $object_id   = 0;
 	protected $embed_args  = array();
 	protected $object_type = 'post';
 	protected $ajax_update = false;
 
-
 	/**
 	 * Handles our oEmbed ajax request
 	 * @since  0.9.5
@@ -60,7 +63,6 @@ public function oembed_handler() {
 		wp_send_json_success( $html );
 	}
 
-
 	/**
 	 * Retrieves oEmbed from url/object ID
 	 * @since  0.9.5
@@ -138,7 +140,6 @@ public function get_oembed( $args ) {
 
 	}
 
-
 	/**
 	 * Hijacks retrieving of cached oEmbed.
 	 * Returns cached data from relevant object metadata (vs postmeta)
@@ -166,7 +167,6 @@ public function hijack_oembed_cache_get( $check, $object_id, $meta_key ) {
 
 	}
 
-
 	/**
 	 * Hijacks saving of cached oEmbed.
 	 * Saves cached data to relevant object metadata (vs postmeta)
@@ -190,7 +190,6 @@ public function hijack_oembed_cache_set( $check, $object_id, $meta_key, $meta_va
 		return true;
 	}
 
-
 	/**
 	 * Saves the cached oEmbed value to relevant object metadata (vs postmeta)
 	 *

diff --git a/includes/CMB2_Boxes.php b/includes/CMB2_Boxes.php
@@ -1,6 +1,12 @@
 <?php
 /**
- * Stores each CMB2 instance
+ * A CMB2 object instance registry for storing every CMB2 instance.
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
  */
 class CMB2_Boxes {
 
@@ -9,28 +15,50 @@ class CMB2_Boxes {
 	 * @var   array
 	 * @since 2.0.0
 	 */
-	protected static $meta_boxes = array();
+	protected static $cmb2_instances = array();
 
-	public static function add( $meta_box ) {
-		self::$meta_boxes[ $meta_box->cmb_id ] = $meta_box;
+	/**
+	 * Add a CMB2 instance object to the registry
+	 * @since 1.X.X
+	 * @param CMB2  $cmb_instance CMB2 instance
+	 */
+	public static function add( CMB2 $cmb_instance ) {
+		self::$cmb2_instances[ $cmb_instance->cmb_id ] = $cmb_instance;
 	}
 
-	public static function remove( $meta_box_id ) {
-		if ( array_key_exists( $meta_box_id, self::$meta_boxes ) ) {
-			unset( self::$meta_boxes[ $meta_box_id ] );
+	/**
+	 * Remove a CMB2 instance object to the registry
+	 * @since  1.X.X
+	 * @param  string $cmb_id A CMB2 instance id
+	 */
+	public static function remove( $cmb_id ) {
+		if ( array_key_exists( $cmb_id, self::$cmb2_instances ) ) {
+			unset( self::$cmb2_instances[ $cmb_id ] );
 		}
 	}
 
+	/**
+	 * Retrieve a CMB2 instance by cmb id
+	 * @since  1.X.X
+	 * @param  string $cmb_id A CMB2 instance id
+	 *
+	 * @return mixed          False or CMB2 object instance
+	 */
 	public static function get( $cmb_id ) {
-		if ( empty( self::$meta_boxes ) || empty( self::$meta_boxes[ $cmb_id ] ) ) {
+		if ( empty( self::$cmb2_instances ) || empty( self::$cmb2_instances[ $cmb_id ] ) ) {
 			return false;
 		}
 
-		return self::$meta_boxes[ $cmb_id ];
+		return self::$cmb2_instances[ $cmb_id ];
 	}
 
+	/**
+	 * Retrieve all CMB2 instances registered
+	 * @since  1.X.X
+	 * @return array Array of all registered metaboxes
+	 */
 	public static function get_all() {
-		return self::$meta_boxes;
+		return self::$cmb2_instances;
 	}
 
 }
diff --git a/includes/CMB2_Field.php b/includes/CMB2_Field.php
@@ -1,10 +1,15 @@
 <?php
-
 /**
- * CMB field class
+ * CMB2 field objects
  *
  * @since  1.1.0
  *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
+ *
  * @method string _id()
  * @method string type()
  * @method mixed fields()

diff --git a/includes/CMB2_Options.php b/includes/CMB2_Options.php
@@ -1,7 +1,19 @@
 <?php
+/**
+ * CMB2 Utility classes for handling multi-dimensional array data for options
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
+ */
 
 /**
  * Retrieves an instance of CMB2_Option based on the option key
+ *
+ * @package   CMB2
+ * @author    WebDevStudios
  */
 class CMB2_Options {
 	/**
@@ -24,6 +36,9 @@ public static function get( $option_key ) {
 /**
  * Handles getting/setting of values to an option array
  * for a specific option key
+ *
+ * @package   CMB2
+ * @author    WebDevStudios
  */
 class CMB2_Option {
 

diff --git a/includes/CMB2_Sanitize.php b/includes/CMB2_Sanitize.php
@@ -1,8 +1,15 @@
 <?php
-
 /**
- * CMB field validation
+ * CMB field sanitization
+ *
  * @since  0.0.4
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
+ *
  * @method string _id()
  */
 class CMB2_Sanitize {

diff --git a/includes/CMB2_Show_Filters.php b/includes/CMB2_Show_Filters.php
@@ -1,13 +1,19 @@
 <?php
-
 /**
  * Show On Filters
- * Use the 'cmb2_show_on' filter to further refine the conditions under which a metabox is displayed.
+ * Use the 'cmb2_show_on' filter to further refine the conditions
+ * under which a metabox is displayed.
  * Below you can limit it by ID and page template
  *
  * All methods in this class are automatically filtered
  *
  * @since  1.0.0
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
  */
 class CMB2_Show_Filters {
 

diff --git a/includes/CMB2_Types.php b/includes/CMB2_Types.php
@@ -1,13 +1,16 @@
 <?php
-
 /**
- * CMB field types
+ * CMB field type objects
  *
- * @todo test taxonomy methods with non-post objects
- * @todo test all methods with non-post objects
  * @todo Date/Time fields should store date format as data attribute for JS
  *
  * @since  1.0.0
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
  */
 class CMB2_Types {
 

diff --git a/includes/CMB2_Utils.php b/includes/CMB2_Utils.php
@@ -1,8 +1,14 @@
 <?php
-
 /**
- * CMB field class
+ * CMB2 Utilities
+ *
  * @since  1.1.0
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
  */
 class CMB2_Utils {
 

diff --git a/includes/CMB2_hookup.php b/includes/CMB2_hookup.php
@@ -1,5 +1,16 @@
 <?php
-
+/**
+ * Handles hooking CMB2 forms/metaboxes into the post/attachement/user screens
+ * and handles hooking in and saving those fields.
+ *
+ * @since  2.0.0
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
+ */
 class CMB2_hookup {
 
 	/**

diff --git a/includes/helper-functions.php b/includes/helper-functions.php
@@ -1,4 +1,13 @@
 <?php
+/**
+ * CMB2 Helper Functions
+ *
+ * @category  WordPress_Plugin
+ * @package   CMB2
+ * @author    WebDevStudios
+ * @license   GPL-2.0+
+ * @link      http://webdevstudios.com
+ */
 
 /**
  * Helper function to provide directory path to CMB

diff --git a/init.php b/init.php
@@ -1,5 +1,11 @@
 <?php
 /**
+ * @category     WordPress_Plugin
+ * @package      CMB2
+ * @author       WebDevStudios
+ * @license      GPL-2.0+
+ * @link         http://webdevstudios.com
+ *
  * Plugin Name:  CMB2
  * Plugin URI:   https://github.com/WebDevStudios/CMB2
  * Description:  CMB2 will create metaboxes and forms with custom fields that will blow your mind.
@@ -45,7 +51,15 @@
 if ( ! class_exists( 'cmb2_bootstrap_205_trunk', false ) ) {
 
 	/**
-	 * Check for newest version of CMB
+	 * Checks for newest version of CMB2
+	 *
+	 * @since  2.0.0
+	 *
+	 * @category  WordPress_Plugin
+	 * @package   CMB2
+	 * @author    WebDevStudios
+	 * @license   GPL-2.0+
+	 * @link      http://webdevstudios.com
 	 */
 	class cmb2_bootstrap_205_trunk {