docs: update docblocks

src/admin/class-footnotes-admin.php

@@ -59,15 +59,21 @@ class Footnotes_Admin {
 	 * Include the following files that provide the admin-specific functionality
 	 * of this plugin:
 	 *
-	 * - `Footnotes_WYSIWYG`. TODO
+	 * - `Footnotes_WYSIWYG`. Provides plugin integration with the WYSIWYG editor.
-	 * - `Footnotes_Layout_Settings`. TODO
+	 * - `Footnotes_Layout_Settings`. Defines the plugin dashboard page(s).
 	 *
 	 * @since    2.8.0
 	 * @access   private
 	 */
 	private function load_dependencies() {
-		// TODO: neaten up and document once placements and names are settled.
+		/**
+		 * The class responsible for WYSIWYG editor integration.
+		 */
 		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'admin/class-footnotes-wysiwyg.php';
+		
+		/**
+		 * The class responsible for constructing the plugin dashboard page(s).
+		 */
 		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'admin/layout/class-footnotes-layout-init.php';
 
 		new Footnotes_Layout_Init();

src/admin/layout/class-footnotes-layout-init.php

@@ -2,9 +2,10 @@
 /**
  * Includes the Plugin settings menu.
  *
- * @filesource
- * @package footnotes
  * @since  1.5.0
+ *
+ * @package    footnotes
+ * @subpackage footnotes/admin
  */
 
 require_once dirname( __FILE__, 3 ) . '/includes/class-footnotes-settings.php';

src/admin/layout/class-footnotes-layout-settings.php

@@ -2,10 +2,7 @@
 /**
  * Includes the Plugin Class to display all Settings.
  *
- * @filesource
- * @package footnotes
  * @since 1.5.0
- *
  * @since 2.0.4  restore arrow settings
  * @since 2.1.0  read-on button label
  * @since 2.1.1  options for ref container and alternative tooltips
@@ -39,6 +36,9 @@
  * @since 2.4.0  footnote shortcode syntax validation
  * @since 2.5.0  Shortcode syntax validation: add more information around the setting, thanks to @andreasra
  * @link https://wordpress.org/support/topic/warning-unbalanced-footnote-start-tag-short-code-before/
+ *
+ * @package    footnotes
+ * @subpackage footnotes/admin/layout
  */
 
 require_once dirname( __FILE__ ) . '/class-footnotes-layout-engine.php';

src/includes/class-footnotes-config.php

@@ -2,11 +2,11 @@
 /**
  * Includes the Plugin Constants class to load all Plugin constant vars like Plugin name, etc.
  *
- * @filesource
- * @package footnotes
  * @since 1.5.0
- *
  * @since 2.0.4  add Public Plugin name for dashboard heading
+ *
+ * @package footnotes
+ * @sunpackage footnotes/includes
  */
 
 /**

src/includes/class-footnotes-convert.php

@@ -2,11 +2,11 @@
 /**
  * Includes the Convert Class.
  *
- * @filesource
- * @package footnotes
  * @since 1.5.0
- *
  * @since 2.2.0  add lowercase Roman
+ *
+ * @package footnotes
+ * @sunpackage footnotes/includes
  */
 
 /**

src/includes/class-footnotes-settings.php

@@ -2,15 +2,16 @@
 /**
  * Includes the Settings class to handle all Plugin settings.
  *
- * @filesource
- * @package footnotes
- * @since 1.5.0
- *
  * The constants are ordered by ascending version so their docblocks can replace most of this list.
+ *
+ * @since 1.5.0
  * @since 2.0.0  Update: **symbol for backlinks** removed; hyperlink moved to the reference number.
  * @since 2.0.4  Update: Restore arrow settings to customize or disable the now prepended arrow symbol, thanks to @mmallett issue report.
  * @since 2.0.7  BUGFIX: Hooks: Default-disable 'the_post', thanks to @spaceling @markcheret @nyamachi @whichgodsaves @spiralofhope2 @mmallett @andreasra @widecast @ymorin007 @tashi1es bug reports.
  * @since 2.1.3  Bugfix: Hooks: disable the_excerpt hook by default to fix issues, thanks to @nikelaos bug report.
+ *
+ * @package footnotes
+ * @subpackage footnotes/includes
  */
 
 require_once dirname( __FILE__ ) . '/class-footnotes-convert.php';

src/includes/class-footnotes-template.php

@@ -2,12 +2,12 @@
 /**
  * Includes the Template Engine to load and handle all Template files of the Plugin.
  *
- * @filesource
- * @package footnotes
  * @since 1.5.0
- *
  * @since 2.2.6  Adding: Templates: support for custom templates in sibling folder, thanks to @misfist issue report.
  * @since 2.5.0  Adding: Templates: Enable template location stack, thanks to @misfist issue report and code contribution.
+ *
+ * @package footnotes
+ * @subpackage footnotes/includes
  */
 
 /**

src/includes/class-footnotes.php

@@ -82,10 +82,14 @@ class Footnotes {
 	 *
 	 * Include the following files that make up the plugin:
 	 *
-	 * - Footnotes_Loader. Orchestrates the hooks of the plugin.
+	 * - `Footnotes_Loader`. Orchestrates the hooks of the plugin.
-	 * - Footnotes_i18n. Defines internationalization functionality.
+	 * - `Footnotes_i18n`. Defines internationalization functionality.
-	 * - Footnotes_Admin. Defines all hooks for the admin area.
+	 * - `Footnotes_Config`. Defines plugin details.
-	 * - Footnotes_Public. Defines all hooks for the public side of the site.
+	 * - `Footnotes_Convert`. Provides conversion methods.
+	 * - `Footnotes_Settings`. Defines customisable plugin settings.
+	 * - `Footnotes_Template`. Handles template rendering.
+	 * - `Footnotes_Admin`. Defines all hooks for the admin area.
+	 * - `Footnotes_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.
@@ -106,7 +110,10 @@ class Footnotes {
 		 * of the plugin.
 		 */
 		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-i18n.php';
-		// TODO: neaten up and document once placements and names are settled.
+		
+		/**
+		 * The various utility classes.
+		 */
 		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-config.php';
 		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-convert.php';
 		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-settings.php';

src/public/class-footnotes-public.php

@@ -41,7 +41,7 @@ class Footnotes_Public {
 	 * The Plugin task.
 	 *
 	 * @since 1.5.0
-	 * @since 2.8.0 Moved to `Footnotes_Public` class.
+	 * @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
 	 * @var Task $task The Plugin task.
 	 */
 	public $a_obj_task = null;
@@ -50,7 +50,7 @@ class Footnotes_Public {
 	 * Flag for using tooltips.
 	 *
 	 * @since 2.4.0
-	 * @since 2.8.0 Moved to `Footnotes_Public` class.
+	 * @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
 	 * @var bool $tooltips_enabled Whether tooltips are enabled or not.
 	 */
 	public static $a_bool_tooltips_enabled = false;
@@ -59,7 +59,7 @@ class Footnotes_Public {
 	 * Allows to determine whether alternative tooltips are enabled.
 	 *
 	 * @since 2.1.1
-	 * @since 2.8.0 Moved to `Footnotes_Public` class.
+	 * @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
 	 * @var bool
 	 */
 	public static $a_bool_alternative_tooltips_enabled = false;
@@ -68,7 +68,7 @@ class Footnotes_Public {
 	 * Allows to determine whether AMP compatibility mode is enabled.
 	 *
 	 * @since 2.6.0  (release)
-	 * @since 2.8.0 Moved to `Footnotes_Public` class.
+	 * @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
 	 * @var bool
 	 */
 	public static $a_bool_amp_enabled = false;
@@ -77,7 +77,7 @@ class Footnotes_Public {
 	 * Allows to determine the script mode among jQuery or plain JS.
 	 *
 	 * @since 2.5.6
-	 * @since 2.8.0 Moved to `Footnotes_Public` class.
+	 * @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
 	 * @var str   'js'      Plain JavaScript.
 	 *            'jquery'  Use jQuery libraries.
 	 */
@@ -131,33 +131,15 @@ class Footnotes_Public {
 	/**
 	 * Register the stylesheets for the public-facing side of the site.
 	 *
-	 * @since    2.8.0
+	 * Enables enqueuing the formatted individual stylesheets if `PRODCUTION_ENV` 
+	 * is true (set in `footnotes.php`).
+	 *
+	 * @since 1.5.0
+	 * @since 2.5.5 Change stylesheet scheme.
+	 * @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
 	 */
 	public function enqueue_styles() {
-		/**
-		 * Enables enqueuing a new-scheme stylesheet.
-		 *
-		 * Enables enqueuing the formatted individual stylesheets if false.
-		 * WARNING: This facility is designed for development and must NOT be used in production.
-		 *
-		 * The Boolean may be set at the bottom of the plugin's main PHP file.
-		 *
-		 * @see footnotes.php
-		 *
-		 * @since 2.5.5
-		 * @since 2.8.0 Moved into `Footnotes_Public` class.
-		 */
 		if ( PRODUCTION_ENV ) {
-
-			/**
-			 * Enqueues a minified united external stylesheet in production.
-			 *
-			 * The media scope argument 'all' is the default.
-			 * No need to use '-css' in the handle, as this is appended automatically.
-			 *
-			 * @since 2.5.5
-			 * @since 2.8.0 Moved into `Footnotes_Public` class.
-			 */
 			// Set tooltip mode for use in stylesheet name.
 			if ( self::$a_bool_tooltips_enabled ) {
 
@@ -215,7 +197,11 @@ class Footnotes_Public {
 	/**
 	 * Register the JavaScript for the public-facing side of the site.
 	 *
-	 * @since    2.8.0
+	 * @since 1.5.0
+	 * @since 2.0.0 Add jQueryUI dependency.
+	 * @since 2.1.2 Add jQuery Tools dependency.
+	 * @since 2.5.6 Add jQuery dependency.
+	 * @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
 	 */
 	public function enqueue_scripts() {
 		/**
@@ -227,7 +213,6 @@ class Footnotes_Public {
 		 * but still enabled by default.
 		 *
 		 * @since 2.5.6
-		 * @since 2.8.0 Moved into `Footnotes_Public` class.
 		 */
 		if ( ! self::$a_bool_amp_enabled ) {
 
@@ -246,10 +231,7 @@ class Footnotes_Public {
 				 * No '-js' in the handle, is appended automatically.
 				 * Deferring to the footer breaks jQuery tooltip display.
 				 *
-				 * Add versioning.
-				 *
 				 * @since 2.1.2
-				 * @since 2.8.0 Moved into `Footnotes_Public` class.
 				 */
 				wp_enqueue_script( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'js/jquery.tools' . ( ( PRODUCTION_ENV ) ? '.min' : '' ) . '.js', array(), '1.2.7.redacted.2', false );
 
@@ -259,7 +241,6 @@ class Footnotes_Public {
 				 * If alternative tooltips are enabled, these libraries are not needed.
 				 *
 				 * @since 2.0.0
-				 * @since 2.8.0 Moved into `Footnotes_Public` class.
 				 */
 				wp_enqueue_script( 'jquery-ui-core' );
 				wp_enqueue_script( 'jquery-ui-widget' );

src/public/widget/class-footnotes-widget-base.php

@@ -2,11 +2,11 @@
 /**
  * Widget base.
  *
- * @filesource
- * @package footnotes
  * @since 1.5.0
- *
  * @since 1.6.4  Update: replace deprecated function WP_Widget() with recommended __construct(), thanks to @dartiss code contribution.
+ *
+ * @package footnotes
+ * @subpackage footnotes/public/widget
  */
 
 /**

src/public/widget/class-footnotes-widget-reference-container.php

@@ -2,12 +2,13 @@
 /**
  * Includes the Plugin Widget to put the Reference Container to the Widget area.
  *
- * @filesource
- * @package footnotes
  * @since 1.5.0
+ *
+ * @package footnotes
+ * @subpackage footnotes/public/widget
  */
 
-require_once dirname( __FILE__ ) . '/class-footnotes-widget-base.php';
+require_once plugin_dir_path( dirname( __FILE__ ) ) . 'widget/class-footnotes-widget-base.php';
 
 /**
  * Registers a Widget to put the Reference Container to the widget area.