From 560e5959a531e73b910434e3d623e88eafb6a257 Mon Sep 17 00:00:00 2001
From: Tom McFarlin <tom@tommcfarlin.com>
Date: Tue, 29 Jul 2014 16:56:18 -0400
Subject: [PATCH] Documenting classes

Documenting classes that are core to each plugin, while also leaving other classes undocumented for an implementation-specific basis.
---
 .../trunk/admin/class-plugin-name-admin.php   |  18 ++--
 .../trunk/admin/css/plugin-name-admin.css     |   2 +-
 .../trunk/includes/class-plugin-name-i18n.php |  37 +++----
 .../includes/class-plugin-name-loader.php     | 100 +++++++++---------
 .../trunk/includes/class-plugin-name.php      |  96 +++++++++--------
 .../trunk/public/class-plugin-name-public.php |  19 ++--
 6 files changed, 137 insertions(+), 135 deletions(-)

diff --git a/plugin-name/trunk/admin/class-plugin-name-admin.php b/plugin-name/trunk/admin/class-plugin-name-admin.php
index 9e66dd2..8647c4b 100644
--- a/plugin-name/trunk/admin/class-plugin-name-admin.php
+++ b/plugin-name/trunk/admin/class-plugin-name-admin.php
@@ -24,29 +24,27 @@
 class Plugin_Name_Admin {
 
 	/**
-	 * Short description. (use period)
+	 * The version of this plugin.
 	 *
 	 * @since    1.0.0
 	 * @access   private
-	 * @var      type    $var    Description.
+	 * @var      string    $version    The current version of this plugin.
 	 */
 	private $version;
 
 	/**
-	 * Short description. (use period)
+	 * Initialize the class and set its properties.
 	 *
 	 * @since    1.0.0
-	 * @access   private
-	 * @var      type    $var    Description.
+	 * @access   public
+	 * @var      string    $version    The version of this plugin.
 	 */
 	public function __construct( $version ) {
 		$this->version = $version;
 	}
 
 	/**
-	 * Short description. (use period)
-	 *
-	 * Long description.
+	 * Register the stylesheets for the Dashboard.
 	 *
 	 * @since    1.0.0
 	 */
@@ -69,9 +67,7 @@ class Plugin_Name_Admin {
 	}
 
 	/**
-	 * Short description. (use period)
-	 *
-	 * Long description.
+	 * Register the JavaScript for the dashboard.
 	 *
 	 * @since    1.0.0
 	 */
diff --git a/plugin-name/trunk/admin/css/plugin-name-admin.css b/plugin-name/trunk/admin/css/plugin-name-admin.css
index b3266b8..e46ea29 100644
--- a/plugin-name/trunk/admin/css/plugin-name-admin.css
+++ b/plugin-name/trunk/admin/css/plugin-name-admin.css
@@ -1,4 +1,4 @@
 /**
- * All of the CSS for your Dashboard-specific functionality should be
+ * All of the CSS for your dashboard-specific functionality should be
  * included in this file.
  */
\ No newline at end of file
diff --git a/plugin-name/trunk/includes/class-plugin-name-i18n.php b/plugin-name/trunk/includes/class-plugin-name-i18n.php
index 4f06d72..8905dfa 100644
--- a/plugin-name/trunk/includes/class-plugin-name-i18n.php
+++ b/plugin-name/trunk/includes/class-plugin-name-i18n.php
@@ -1,22 +1,25 @@
 <?php
 
 /**
- * Define a short description for what this class does (no period)
+ * Define the internationalization functionality.
+ *
+ * Loads and defines the internationalization files for this plugin
+ * so that its ready for translation.
+ *
+ * @link       http://example.com
+ * @since      1.0.0
  *
  * @package    Plugin_Name
  * @subpackage Plugin_Name/includes
- * @author     Your Name <email@example.com>
- * @license    GPL-2.0+
- * @link       http://example.com
- * @copyright  2014 Your Name or Company Name
- * @since      1.0.0
  */
 
 /**
- * Define a short description for what this class does.
+ * Define the internationalization functionality.
  *
- * Define a longer description for the purpose of this class.
+ * Loads and defines the internationalization files for this plugin
+ * so that its ready for translation.
  *
+ * @since      1.0.0
  * @package    Plugin_Name
  * @subpackage Plugin_Name/includes
  * @author     Your Name <email@example.com>
@@ -24,7 +27,7 @@
 class Plugin_Name_i18n {
 
 	/**
-	 * Short description. (use period)
+	 * Short Description. (use period)
 	 *
 	 * @since    1.0.0
 	 * @access   private
@@ -33,27 +36,25 @@ class Plugin_Name_i18n {
 	private $domain;
 
 	/**
-	 *
 	 * Load the plugin text domain for translation.
 	 *
 	 * @since    1.0.0
 	 */
 	public function load_plugin_textdomain() {
 
-		$locale = apply_filters( 'plugin_locale', get_locale(), $this->domain );
-
-		load_textdomain( $this->domain, trailingslashit( WP_LANG_DIR ) . $this->domain . '/' . $this->domain . '-' . $locale . '.mo' );
-		load_plugin_textdomain( $this->domain, FALSE, basename( plugin_dir_path( dirname( __FILE__ ) ) ) . '/languages/' );
+		load_plugin_textdomain(
+			$this->domain,
+			FALSE,
+			dirname( dirname( plugin_basename( __FILE__ ) ) ) . '/languages/'
+		);
 
 	}
 
 	/**
-	 * Short description. (use period)
-	 *
-	 * Long description.
+	 * Set the domain equal to that of the specified domain.
 	 *
 	 * @since    1.0.0
-	 * @param    float    $domain    TODO
+	 * @param    string    $domain    The domain that represents the locale of this plugin.
 	 */
 	public function set_domain( $domain ) {
 		$this->domain = $domain;
diff --git a/plugin-name/trunk/includes/class-plugin-name-loader.php b/plugin-name/trunk/includes/class-plugin-name-loader.php
index ef6cbac..f1413e1 100644
--- a/plugin-name/trunk/includes/class-plugin-name-loader.php
+++ b/plugin-name/trunk/includes/class-plugin-name-loader.php
@@ -1,7 +1,7 @@
 <?php
 
 /**
- * Define a short description for what this class does (no period)
+ * Register all actions and filters
  *
  * @package    Plugin_Name
  * @subpackage Plugin_Name/includes
@@ -13,9 +13,11 @@
  */
 
 /**
- * Define a short description for what this class does.
+ * Register all actions and filters.
  *
- * Define a longer description for the purpose of this class.
+ * Maintain a list of all hooks that are registered throughout
+ * the plugin, and register them with the WordPress API. Call the
+ * run function to execute the list of actions and filters.
  *
  * @package    Plugin_Name
  * @subpackage Plugin_Name/includes
@@ -24,28 +26,28 @@
 class Plugin_Name_Loader {
 
 	/**
-	 * Short description. (use period)
+	 * The array of actions registered with WordPress.
 	 *
 	 * @since    1.0.0
-	 * @access   private
-	 * @var      type    $var    Description.
+	 * @access   protected
+	 * @var      array    $actions    The actions registered with WordPress to fire when the plugin loads.
 	 */
 	protected $actions;
 
 	/**
-	 * Short description. (use period)
+	 * The array of filters registered with WordPress.
 	 *
 	 * @since    1.0.0
-	 * @access   private
-	 * @var      type    $var    Description.
+	 * @access   protected
+	 * @var      array    $filters    The filters registered with WordPress to fire when the plugin loads.
 	 */
 	protected $filters;
 
 	/**
-	 * Short description. (use period)
+	 * Initialize the collections used to maintain the actions and filters.
 	 *
 	 * @since    1.0.0
-	 * @access   private
+	 * @access   public
 	 */
 	public function __construct() {
 
@@ -55,51 +57,57 @@ class Plugin_Name_Loader {
 	}
 
 	/**
-	 * Short description. (use period)
+	 * Add a new action to the collection to be registered with WordPress.
 	 *
 	 * @since    1.0.0
-	 * @access   private
-	 * @var      type                $var    Description.
-	 * @var      type                $var    Description.
-	 * @var      type                $var    Description.
-	 * @var      type    Optional    $var    Description.
+	 * @access   public
+	 * @var      string               $hook             The name of the WordPress action that is being registered.
+	 * @var      object               $component        A reference to the instance of the object on which the action is defined.
+	 * @var      string               $callback         The name of the function definition on the $component.
+	 * @var      int      Optional    $priority         The priority at which the function should be fired.
+	 * @var      array    Optional    $accepted_args    The collection of arguments that should be passed to the $callback.
 	 */
-	public function add_action( $hook, $component, $callback, $priority = 10 ) {
-		$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority );
+	public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = array() ) {
+		$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args );
 	}
 
 	/**
-	 * Short description. (use period)
+	 * Add a new filter to the collection to be registered with WordPress.
 	 *
 	 * @since    1.0.0
-	 * @access   private
-	 * @var      type                $var    Description.
-	 * @var      type                $var    Description.
-	 * @var      type                $var    Description.
-	 * @var      type    Optional    $var    Description.
+	 * @access   public
+	 * @var      string               $hook             The name of the WordPress filter that is being registered.
+	 * @var      object               $component        A reference to the instance of the object on which the filter is defined.
+	 * @var      string               $callback         The name of the function definition on the $component.
+	 * @var      int      Optional    $priority         The priority at which the function should be fired.
+	 * @var      array    Optional    $accepted_args    The collection of arguments that should be passed to the $callback.
 	 */
-	public function add_filter( $hook, $component, $callback, $priority = 10 ) {
-		$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority );
+	public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = array() ) {
+		$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args = array() );
 	}
 
 	/**
-	 * Short description. (use period)
+	 * A utility function that is used to register the actions and hooks into a single
+	 * collection.
 	 *
 	 * @since    1.0.0
 	 * @access   private
-	 * @var      type                $var    Description.
-	 * @var      type                $var    Description.
-	 * @var      type                $var    Description.
-	 * @var      type                $var    Description.
-	 * @var      type    Optional    $var    Description.
+	 * @var      array                $hooks            The collection of hooks that is being registered (that is, actions or filters).
+	 * @var      string               $hook             The name of the WordPress filter that is being registered.
+	 * @var      object               $component        A reference to the instance of the object on which the filter is defined.
+	 * @var      string               $callback         The name of the function definition on the $component.
+	 * @var      int      Optional    $priority         The priority at which the function should be fired.
+	 * @var      array    Optional    $accepted_args    The collection of arguments that should be passed to the $callback.
+	 * @return   type                                   The collection of actions and filters registered with WordPress.
 	 */
-	private function add( $hooks, $hook, $component, $callback, $priority ) {
+	private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) {
 
 		$hooks[] = array(
-			'hook'      => $hook,
-			'component' => $component,
-			'callback'  => $callback,
-			'priority'  => $priority
+			'hook'          => $hook,
+			'component'     => $component,
+			'callback'      => $callback,
+			'priority'      => $priority,
+			'accepted_args' => $accepted_args
 		);
 
 		return $hooks;
@@ -107,28 +115,18 @@ class Plugin_Name_Loader {
 	}
 
 	/**
-	 * Short description. (use period)
-	 *
-	 * Long description.
+	 * Register the filters and actions with WordPress.
 	 *
 	 * @since    1.0.0
 	 */
 	public function run() {
 
-		/**
-		 * TODO:
-		 * This function is used to define the various hooks that are shared in the
-		 * both the dashboard and the public-facing areas of the plugin. This is
-		 * achieved via dependency injection by passing an instance of Plugin_Name
-		 * into this class.
-		 */
-
 		 foreach ( $this->filters as $hook ) {
-			 add_filter( $hook['hook'], array( $hook['component'], $hook['callback'] ), $hook['priority'] );
+			 add_filter( $hook['hook'], array( $hook['component'], $hook['callback'] ), $hook['priority'], $hook['accepted_args'] );
 		 }
 
 		 foreach ( $this->actions as $hook ) {
-			 add_action( $hook['hook'], array( $hook['component'], $hook['callback'] ), $hook['priority'] );
+			 add_action( $hook['hook'], array( $hook['component'], $hook['callback'] ), $hook['priority'], $hook['accepted_args'] );
 		 }
 
 	}
diff --git a/plugin-name/trunk/includes/class-plugin-name.php b/plugin-name/trunk/includes/class-plugin-name.php
index 1dbad63..66e011b 100644
--- a/plugin-name/trunk/includes/class-plugin-name.php
+++ b/plugin-name/trunk/includes/class-plugin-name.php
@@ -1,11 +1,15 @@
 <?php
 
 /**
- * Short Description (no period)
+ * The core plugin file
  *
- * Long Description.
+ * This is the core plugin file that is used to define internationalization,
+ * dashboard-specific hooks, and public-facing site hooks.
  *
- * @link       http://example.com/
+ * Also maintains the unique identifier of this plugin as well as the current
+ * version of the plugin.
+ *
+ * @link       http://example.com
  * @since      1.0.0
  *
  * @package    Plugin_Name
@@ -25,34 +29,39 @@
 class Plugin_Name {
 
 	/**
-	 * Short Description. (use period)
+	 * The loader that's responsible for maintaining and registering all hooks that power
+	 * the plugin.
 	 *
 	 * @since    1.0.0
-	 * @access   (private, protected, or public)
-	 * @var      type    $var    Description.
+	 * @access   protected
+	 * @var      type    Plugin_Name_Loader    Maintains and registers all hooks for the plugin.
 	 */
 	protected $loader;
 
 	/**
-	 * Short Description. (use period)
+	 * The unique identifier of this plugin.
 	 *
 	 * @since    1.0.0
-	 * @access   (private, protected, or public)
-	 * @var      type    $var    Description.
+	 * @access   protected
+	 * @var      string    $plugin_slug    The slug used to uniquely identify this plugin.
 	 */
 	protected $plugin_slug;
 
 	/**
-	 * Short Description. (use period)
+	 * The current version of the plugin.
 	 *
 	 * @since    1.0.0
-	 * @access   (private, protected, or public)
-	 * @var      type    $var    Description.
+	 * @access   protected
+	 * @var      string    $version    The current version of the plugin.
 	 */
 	protected $version;
 
 	/**
-	 * Short Description. (use period)
+	 * Define the core functionality of the plugin.
+	 *
+	 * Set the plugin slug and the plugin version that can be used throughout the plugin.
+	 * Load the dependencies, define the locale, and set the hooks for the Dashboard and
+	 * the public-facing side of the site.
 	 *
 	 * @since    1.0.0
 	 */
@@ -69,12 +78,20 @@ class Plugin_Name {
 	}
 
 	/**
-	 * Short Description. (use period)
+	 * Load the required dependencies for this plugin.
 	 *
-	 * Long Description.
+	 * Include the following files that make up the plugin:
+	 *
+	 * - Plugin_Name_Loader. Orchestrates the hooks of the plugin.
+	 * - Plugin_Name_i18n. Defines internationalization functionality.
+	 * - Plugin_Name_Admin. Defines all hooks for the dashboard.
+	 * - Plugin_Name_Public. Defines all hooks for the public side of the site.
+	 *
+	 * Create an instance of the loader which will be used to register the hooks
+	 * with WordPress.
 	 *
 	 * @since    1.0.0
-	 * @access   (for functions: only use if private)
+	 * @access   private
 	 */
 	private function load_dependencies() {
 
@@ -106,57 +123,57 @@ class Plugin_Name {
 	}
 
 	/**
-	 * Short Description. (use period)
+	 * Define the locale for this plugin for internationalization.
 	 *
-	 * Long Description.
+	 * Uses the Plugin_Name_i18n class in order to set the domain and to register the hook
+	 * with WordPress.
 	 *
 	 * @since    1.0.0
-	 * @access   (for functions: only use if private)
+	 * @access   private
 	 */
 	private function set_locale() {
 
 		$plugin_i18n = new Plugin_Name_i18n();
 		$plugin_i18n->set_domain( $this->get_plugin_slug() );
+
 		$this->loader->add_action( 'plugins_loaded', $plugin_i18n, 'load_plugin_textdomain' );
 
 	}
 
 	/**
-	 * Short Description. (use period)
-	 *
-	 * Long Description.
+	 * Register all of the hooks related to the dashboard functionality
+	 * of the plugin.
 	 *
 	 * @since    1.0.0
-	 * @access   (for functions: only use if private)
+	 * @access   private
 	 */
 	private function define_admin_hooks() {
 
 		$plugin_admin = new Plugin_Name_Admin( $this->get_version() );
+
 		$this->loader->add_action( 'admin_enqueue_scripts', $plugin_admin, 'enqueue_styles' );
 		$this->loader->add_action( 'admin_enqueue_scripts', $plugin_admin, 'enqueue_scripts' );
 
 	}
 
 	/**
-	 * Short Description. (use period)
-	 *
-	 * Long Description.
+	 * Register all of the hooks related to the public-facing functionality
+	 * of the plugin.
 	 *
 	 * @since    1.0.0
-	 * @access   (for functions: only use if private)
+	 * @access   private
 	 */
 	private function define_public_hooks() {
 
 		$plugin_public = new Plugin_Name_Public( $this->get_version() );
+
 		$this->loader->add_action( 'wp_enqueue_scripts', $plugin_public, 'enqueue_styles' );
 		$this->loader->add_action( 'wp_enqueue_scripts', $plugin_public, 'enqueue_scripts' );
 
 	}
 
 	/**
-	 * Short Description. (use period)
-	 *
-	 * Long Description.
+	 * Execute the loader to execute all of the hooks with WordPress.
 	 *
 	 * @since    1.0.0
 	 */
@@ -165,36 +182,31 @@ class Plugin_Name {
 	}
 
 	/**
-	 * Short Description. (use period)
-	 *
-	 * Long Description.
+	 * The slug of the plugin used to uniquely identify it within the context of
+	 * WordPress and to define internationalization functionality.
 	 *
 	 * @since     1.0.0
-	 * @return    type    Description
+	 * @return    string    The slug of the plugin.
 	 */
 	public function get_plugin_slug() {
 		return $this->plugin_slug;
 	}
 
 	/**
-	 * Short Description. (use period)
-	 *
-	 * Long Description.
+	 * The reference to the class that orchestrates the hooks with the plugin.
 	 *
 	 * @since     1.0.0
-	 * @return    type    Description
+	 * @return    Plugin_Name_Loader    Orchestrates the hooks of the plugin.
 	 */
 	public function get_loader() {
 		return $this->loader;
 	}
 
 	/**
-	 * Short Description. (use period)
-	 *
-	 * Long Description.
+	 * Retrieve the version number of the plugin.
 	 *
 	 * @since     1.0.0
-	 * @return    type    Description
+	 * @return    string    The version number of the plugin.
 	 */
 	public function get_version() {
 		return $this->version;
diff --git a/plugin-name/trunk/public/class-plugin-name-public.php b/plugin-name/trunk/public/class-plugin-name-public.php
index a348b2c..d8ed3b5 100644
--- a/plugin-name/trunk/public/class-plugin-name-public.php
+++ b/plugin-name/trunk/public/class-plugin-name-public.php
@@ -24,30 +24,27 @@
 class Plugin_Name_Public {
 
 	/**
-	 * Short description. (use period)
+	 * The version of this plugin.
 	 *
 	 * @since    1.0.0
 	 * @access   private
-	 * @var      type    $var    Description.
+	 * @var      string    $version    The current version of this plugin.
 	 */
 	private $version;
 
 	/**
-	 * Short description. (use period)
-	 *
-	 * Long description.
+	 * Initialize the class and set its properties.
 	 *
 	 * @since    1.0.0
-	 * @param    float    $version    TODO
+	 * @access   public
+	 * @var      string    $version    The version of this plugin.
 	 */
 	public function __construct( $version ) {
 		$this->version = $version;
 	}
 
 	/**
-	 * Short description. (use period)
-	 *
-	 * Long description.
+	 * Register the stylesheets for the public-facing side of the site.
 	 *
 	 * @since    1.0.0
 	 */
@@ -70,9 +67,7 @@ class Plugin_Name_Public {
 	}
 
 	/**
-	 * Short description. (use period)
-	 *
-	 * Long description.
+	 * Register the stylesheets for the public-facing side of the site.
 	 *
 	 * @since    1.0.0
 	 */