From bfeb11d5ad726055ce7cb8f070d964a263509dcf Mon Sep 17 00:00:00 2001
From: Rumperuu <me+git@bengoldsworthy.net>
Date: Thu, 29 Apr 2021 20:57:30 +0100
Subject: [PATCH] docs: update docblocks

---
 .../class-footnotes-layout-settings.php       |   2 +-
 src/footnotes.php                             |  39 ++++--
 src/includes/class-footnotes-activator.php    |  21 +--
 src/includes/class-footnotes-config.php       |  71 ++++++----
 src/includes/class-footnotes-convert.php      |  92 +++++++------
 src/includes/class-footnotes-deactivator.php  |  21 +--
 src/includes/class-footnotes-i18n.php         |  34 ++---
 src/includes/class-footnotes-loader.php       |  87 +++++++------
 src/includes/class-footnotes-settings.php     |  67 +++++-----
 src/includes/class-footnotes-template.php     | 113 ++++++++--------
 src/includes/class-footnotes.php              | 122 ++++++++++--------
 11 files changed, 363 insertions(+), 306 deletions(-)

diff --git a/src/admin/layout/class-footnotes-layout-settings.php b/src/admin/layout/class-footnotes-layout-settings.php
index a6c42c4..7976add 100644
--- a/src/admin/layout/class-footnotes-layout-settings.php
+++ b/src/admin/layout/class-footnotes-layout-settings.php
@@ -1152,7 +1152,7 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
 	 * Edited:
 	 * @since 2.1.6  drop localized notices for CSS classes as the number increased to 16
 	 *        list directly in the template, as CSS is in English anyway
-	 * @see admin/partials/customize-css.html
+	 * @link ../partials/customize-css.html
 	 *
 	 * @since 2.2.2  migrate Custom CSS to a dedicated tab
 	 * @since 2.3.0  say 'copy-paste' instead of 'cut and paste' since cutting is not needed
diff --git a/src/footnotes.php b/src/footnotes.php
index 1f31b75..8413518 100755
--- a/src/footnotes.php
+++ b/src/footnotes.php
@@ -7,11 +7,11 @@
  * registers the activation and deactivation functions, and defines a function
  * that starts the plugin.
  *
- * @author Mark Cheret
- * @since 1.0.0
- * @package footnotes
- * @copyright 2021 Mark Cheret (email: mark@cheret.de)
- * @license GPL-3.0-only
+ * @package  footnotes
+ * @license  GPL-3.0-only
+ * @copyright  2021 Mark Cheret (email: mark@cheret.de)
+ *
+ * @since  1.0.0
  *
  * @wordpress-plugin
  * Plugin Name: footnotes
@@ -34,24 +34,33 @@ if ( ! defined( 'WPINC' ) ) {
 }
 
 /**
- * Current plugin version.
+ * The current plugin version.
+ *
+ * @link https://github.com/markcheret/footnotes/wiki/Versioning Versioning Guide
+ *
+ * @global string PLUGIN_VERSION
  *
  * @since 2.1.4
  */
 define( 'PLUGIN_VERSION', '2.8.0d' );
 
 /**
- * Defines the current environment ('development' or 'production').
+ * The current environment ('development' or 'production').
  *
  * This primarily affects whether minified or unminified files are requested.
  *
+ * @global bool PRODUCTION_ENV
+ *
  * @since 2.5.5
  */
 define( 'PRODUCTION_ENV', false );
 
 /**
- * The code that runs during plugin activation.
- * This action is documented in includes/class-plugin-name-activator.php
+ * Triggers during plugin activation.
+ *
+ * @uses Footnotes_Activator::activate() Method called on plugin activation.
+ *
+ * @since 2.8.0
  */
 function activate_footnotes() {
 	require_once plugin_dir_path( __FILE__ ) . 'includes/class-footnotes-activator.php';
@@ -59,8 +68,11 @@ function activate_footnotes() {
 }
 
 /**
- * The code that runs during plugin deactivation.
- * This action is documented in includes/class-plugin-name-deactivator.php
+ * Triggers during plugin deactivation.
+ *
+ * @uses Footnotes_Deactivator::deactivate() Method called on plugin deactivation.
+ *
+ * @since 2.8.0
  */
 function deactivate_plugin_name() {
 	require_once plugin_dir_path( __FILE__ ) . 'includes/class-footnotes-deactivator.php';
@@ -79,9 +91,8 @@ require plugin_dir_path( __FILE__ ) . 'includes/class-footnotes.php';
 /**
  * Begins execution of the plugin.
  *
- * Since everything within the plugin is registered via hooks,
- * then kicking off the plugin from this point in the file does
- * not affect the page life cycle.
+ * Since everything within the plugin is registered via hooks, then kicking off 
+ * the plugin from this point in the file does not affect the page life cycle.
  *
  * @since 2.8.0
  */
diff --git a/src/includes/class-footnotes-activator.php b/src/includes/class-footnotes-activator.php
index 14212e2..87acc7d 100644
--- a/src/includes/class-footnotes-activator.php
+++ b/src/includes/class-footnotes-activator.php
@@ -1,30 +1,31 @@
 <?php
 /**
- * Fired during plugin activation
+ * File providing `Footnotes_Activator` class.
  *
- * @since      2.8.0
+ * @package  footnotes
+ * @subpackage  includes
  *
- * @package    footnotes
- * @subpackage includes
+ * @since  2.8.0
  */
 
 /**
- * Fired during plugin activation.
+ * Class providing action(s) on plugin activation.
  *
  * This class defines all code necessary to run during the plugin's activation.
  *
- * @since      2.8.0
- * @package    footnotes
- * @subpackage includes
+ * @package  footnotes
+ * @subpackage  includes
+ *
+ * @since  2.8.0
  */
 class Footnotes_Activator {
 
 	/**
-	 * Runs when the Plugin is deactivated.
+	 * Runs when the plugin is deactivated.
 	 *
 	 * Currently NOP.
 	 *
-	 * @since    2.8.0
+	 * @since  2.8.0
 	 */
 	public static function activate() {
 		// Nothing yet.
diff --git a/src/includes/class-footnotes-config.php b/src/includes/class-footnotes-config.php
index 17b8651..d952ccd 100644
--- a/src/includes/class-footnotes-config.php
+++ b/src/includes/class-footnotes-config.php
@@ -1,65 +1,84 @@
 <?php
 /**
- * Includes the Plugin Constants class to load all Plugin constant vars like Plugin name, etc.
+ * File providing the `Footnotes_Config` class.
  *
- * @since 1.5.0
- * @since 2.0.4  add Public Plugin name for dashboard heading
+ * @package  footnotes
+ * @subpackage  includes
  *
- * @package footnotes
- * @subpackage includes
+ * @since  1.5.0
+ * @since  2.8.0  Rename file from `config.php` to `class-footnotes-config.php`.
+ * @todo  Remove.
+ * @deprecated
  */
 
 /**
- * Contains all Plugin Constants. Contains no Method or Property.
+ * Class defining plugin constants.
  *
- * @since 1.5.0
+ * This class contains no methods of properties.
+ *
+ * @since  1.5.0
+ * @todo  Remove.
+ * @deprecated
  */
 class Footnotes_Config {
 	/**
-	 * Public Plugin name.
+	 * Public plugin name.
 	 *
-	 * @since 1.5.0
 	 * @var string
 	 *
-	 * edited classes for v2.0.4
+	 * @since  1.5.0
+	 * @todo  Remove.
+ 	 * @deprecated
 	 */
 	const C_STR_PLUGIN_PUBLIC_NAME = '<span class="footnotes_logo footnotes_logo_part1">foot</span><span class="footnotes_logo footnotes_logo_part2">notes</span>';
 
 	/**
-	 * Public Plugin name for dashboard heading
+	 * Public plugin name for use as a dashboard heading.
 	 *
 	 * After properly displaying in dashboard headings until WPv5.4, the above started
-	 * in WPv5.5 being torn apart as if the headline was text-align:justify and not
-	 * the last line. That ugly display bug badly affected the plugin’s communication.
-	 * The only working solution found so far is using position:fixed in one heading
-	 * that isn’t translated, and dropping the logo in another, translatable heading.
+	 * in WP 5.5 being torn apart as if the headline was `text-align:justify` and not
+	 * the last line. That ugly display bug badly affected the plugin's communication.
+	 * The only working solution found so far is using `position:fixed` in one heading
+	 * that isn't translated, and dropping the logo in another, translatable heading.
 	 *
-	 * @since 2.0.4
-	 * @var string
+	 * @var  string
+	 *
+	 * @since  2.0.4
+	 * @todo  Remove.
+ 	 * @deprecated
 	 */
 	const C_STR_PLUGIN_HEADING_NAME = '<span class="footnotes_logo_heading footnotes_logo_part1_heading">foot</span><span class="footnotes_logo_heading footnotes_logo_part2_heading">notes</span>';
 
 	/**
-	 * Html tag for the LOVE symbol.
+	 * HTML element for the ‘love’ symbol.
 	 *
-	 * @since 1.5.0
-	 * @var string
+	 * @var  string
+	 *
+	 * @since  1.5.0
+	 * @todo  Remove.
+ 	 * @deprecated
 	 */
 	const C_STR_LOVE_SYMBOL = '<span style="color:#ff6d3b; font-weight:bold;">&hearts;</span>';
 
 	/**
-	 * HTML code for the 'love' symbol used in dashboard heading
+	 * HTML element for the ‘love’ symbol used in dashboard heading
 	 *
-	 * @since 2.0.4
-	 * @var string
+	 * @var  string
+	 *
+	 * @since  2.0.4
+	 * @todo  Remove.
+ 	 * @deprecated
 	 */
 	const C_STR_LOVE_SYMBOL_HEADING = '<span class="footnotes_heart_heading">&hearts;</span>';
 
 	/**
-	 * Short code to DON'T display the 'LOVE ME' slug on certain pages.
+	 * Shortcode to NOT display the ‘LOVE ME’ slug on certain pages.
 	 *
-	 * @since 1.5.0
-	 * @var string
+	 * @var  string
+	 *
+	 * @since  1.5.0
+	 * @todo  Remove.
+ 	 * @deprecated
 	 */
 	const C_STR_NO_LOVE_SLUG = '[[no footnotes: love]]';
 }
diff --git a/src/includes/class-footnotes-convert.php b/src/includes/class-footnotes-convert.php
index a3e9944..e307fff 100644
--- a/src/includes/class-footnotes-convert.php
+++ b/src/includes/class-footnotes-convert.php
@@ -1,31 +1,29 @@
 <?php
 /**
- * Includes the Convert Class.
+ * File providing core `Footnotes_Convert` class.
  *
- * @since 1.5.0
- * @since 2.2.0  add lowercase Roman
+ * @package  footnotes
+ * @subpackage  includes
  *
- * @package footnotes
- * @subpackage includes
+ * @since  1.5.0
+ * @since  2.8.0  Rename file from `convert.php` to `class-footnotes-convert.php`.
  */
 
 /**
- * Converts data types and Footnotes specific values.
+ * Class providing variable type and value conversion functions.
  *
  * @since 1.5.0
  */
 class Footnotes_Convert {
 
 	/**
-	 * Converts a integer into the user-defined counter style for the footnotes.
+	 * Converts an integer into the user-defined counter style for the footnotes.
 	 *
-	 * @since 1.5.0
-	 * @param int    $p_int_index Index to be converted.
-	 * @param string $p_str_convert_style Style of the new/converted Index.
-	 * @return string Converted Index as string in the defined counter style.
+	 * @param  int  $p_int_index  Index to be converted.
+	 * @param  string  $p_str_convert_style  Counter style to use.
+	 * @return  string  Converted  Index converted to the defined counter style.
 	 *
-	 * Edited:
-	 * @since 2.2.0  lowercase Roman numerals supported
+	 * @since  1.5.0
 	 */
 	public static function index( $p_int_index, $p_str_convert_style = 'arabic_plain' ) {
 		switch ( $p_str_convert_style ) {
@@ -46,13 +44,17 @@ class Footnotes_Convert {
 	}
 
 	/**
-	 * Converts an integer into latin ascii characters, either lower or upper-case.
-	 * Function available from A to ZZ ( means 676 footnotes at 1 page possible).
+	 * Converts an integer into Latin ASCII characters, either lower or upper-case.
 	 *
-	 * @since 1.0-gamma
-	 * @param int  $p_int_value Value/Index to be converted.
-	 * @param bool $p_bool_upper_case True to convert the value to upper case letter, otherwise to lower case.
-	 * @return string
+	 * This function works from values A–ZZ (meaning there is a limit of 676
+	 * gootnotes per Page).
+	 *
+	 * @param  int  $p_int_value  Value to be converted.
+	 * @param  bool  $p_bool_upper_case  Whether to convert the value to upper-case.
+	 * @return  string
+	 *
+	 * @since  1.0-gamma
+	 * @todo  Replace with built-in char casting.
 	 */
 	private static function to_latin( $p_int_value, $p_bool_upper_case ) {
 		// Output string.
@@ -80,9 +82,11 @@ class Footnotes_Convert {
 	/**
 	 * Converts an integer to a leading-0 integer.
 	 *
-	 * @since 1.0-gamma
-	 * @param int $p_int_value Value/Index to be converted.
-	 * @return string Value with a leading zero.
+	 * @param  int  $p_int_value  Value to be converted.
+	 * @return  string  Value with a leading zero.
+	 *
+	 * @since  1.0-gamma
+	 * @todo  Replace with built-in string formatting.
 	 */
 	private static function to_arabic_leading( $p_int_value ) {
 		// Add a leading 0 if number lower then 10.
@@ -93,15 +97,13 @@ class Footnotes_Convert {
 	}
 
 	/**
-	 * Converts an integer to a romanic letter.
+	 * Converts an integer to a Roman numeral.
 	 *
-	 * @since 1.0-gamma
-	 * @param int  $p_int_value Value/Index to be converted.
-	 * @param bool $p_bool_upper_case Whether to uppercase.
-	 * @return string
+	 * @param  int  $p_int_value  Value to be converted.
+	 * @param  bool  $p_bool_upper_case  Whether to convert the value to upper-case.
+	 * @return  string
 	 *
-	 * Edited:
-	 * @since 2.2.0   optionally lowercase (code from Latin)
+	 * @since  1.0-gamma
 	 */
 	private static function to_romanic( $p_int_value, $p_bool_upper_case ) {
 		// Table containing all necessary romanic letters.
@@ -142,9 +144,11 @@ class Footnotes_Convert {
 	/**
 	 * Converts a string depending on its value to a boolean.
 	 *
-	 * @since 1.0-beta
-	 * @param string $p_str_value String to be converted to boolean.
-	 * @return bool Boolean representing the string.
+	 * @param  string  $p_str_value  String to be converted to boolean.
+	 * @return  bool  Boolean value represented by the string.
+	 *
+	 * @since  1.0-beta
+	 * @todo  Replace with built-in type casting.
 	 */
 	public static function to_bool( $p_str_value ) {
 		// Convert string to lower-case to make it easier.
@@ -163,11 +167,13 @@ class Footnotes_Convert {
 	}
 
 	/**
-	 * Get a html Array short code depending on Arrow-Array key index.
+	 * Get an HTML array short code depending on Arrow-Array key index.
 	 *
-	 * @since 1.3.2
-	 * @param int $p_int_index Index representing the Arrow. If empty all Arrows are specified.
-	 * @return array|string Array of all Arrows if Index is empty otherwise html tag of a specific arrow.
+	 * @param  int  $p_int_index Index representing the arrow. If empty, all arrows are specified.
+	 * @return  array|string  Array of all arrows if index is empty, otherwise HTML tag of a specific arrow.
+	 *
+	 * @since  1.3.2
+	 * @todo  Review.
 	 */
 	public static function get_arrow( $p_int_index = -1 ) {
 		// Define all possible arrows.
@@ -184,14 +190,14 @@ class Footnotes_Convert {
 		return $l_arr_arrows[ $p_int_index ];
 	}
 
-	// phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_var_dump
-	// phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_print_r
+	// phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_var_dump, WordPress.PHP.DevelopmentFunctions.error_log_print_r
 	/**
-	 * Displays a Variable.
+	 * Displays a variable.
 	 *
-	 * @since 1.5.0
-	 * @param mixed $p_mixed_value The variable to display.
-	 * @return void
+	 * @param  mixed  $p_mixed_value  The variable to display.
+	 *
+	 * @since  1.5.0
+	 * @todo  Replace with proper logging/debug functions.
 	 */
 	public static function debug( $p_mixed_value ) {
 		if ( empty( $p_mixed_value ) ) {
@@ -218,5 +224,5 @@ class Footnotes_Convert {
 		}
 		echo '<br/>';
 	}
-	// phpcs:disable
+	// phpcs:enable WordPress.PHP.DevelopmentFunctions.error_log_var_dump, WordPress.PHP.DevelopmentFunctions.error_log_print_r
 }
diff --git a/src/includes/class-footnotes-deactivator.php b/src/includes/class-footnotes-deactivator.php
index 323ab64..4514089 100644
--- a/src/includes/class-footnotes-deactivator.php
+++ b/src/includes/class-footnotes-deactivator.php
@@ -1,30 +1,31 @@
 <?php
 /**
- * Fired during plugin deactivation.
+ * File providing `Footnotes_Deactivator` class.
  *
- * @since       2.8.0
- *
- * @package     footnotes
+ * @package  footnotes
  * @subpackage  includes
+ *
+ * @since  2.8.0
  */
 
 /**
- * Fired during plugin deactivation.
+ * Class providing action(s) on plugin deactivation.
  *
  * This class defines all code necessary to run during the plugin's deactivation.
  *
- * @since      2.8.0
- * @package    footnotes
- * @subpackage includes
+ * @package  footnotes
+ * @subpackage  includes
+ *
+ * @since  2.8.0
  */
 class Footnotes_Deactivator {
 
 	/**
-	 * Runs when the Plugin is deactivated.
+	 * Runs when the plugin is deactivated.
 	 *
 	 * Currently NOP.
 	 *
-	 * @since    2.8.0
+	 * @since  2.8.0
 	 */
 	public static function deactivate() {
 		// Nothing yet.
diff --git a/src/includes/class-footnotes-i18n.php b/src/includes/class-footnotes-i18n.php
index b57643c..e43eb8a 100644
--- a/src/includes/class-footnotes-i18n.php
+++ b/src/includes/class-footnotes-i18n.php
@@ -1,37 +1,37 @@
 <?php // phpcs:disable PEAR.NamingConventions.ValidClassName.Invalid
 /**
- * Define the internationalization functionality
+ * File providing core `Footnotes_i18n` class.
  *
- * Loads and defines the internationalization files for this plugin
- * so that it is ready for translation.
+ * @package  footnotes
+ * @subpackage  includes
  *
- * @since      1.5.0
- * @since      2.8.0 Renamed class to `Footnotes_i18n`.
- *
- * @package    footnotes
- * @subpackage includes
+ * @since  1.5.0
+ * @since  2.8.0  Rename file from `language.php` to `class-footnotes-i18n.php`.
  */
 
 require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-config.php';
 
 /**
- * Define the internationalization functionality.
+ * Class providing internationalization functionality.
  *
- * Loads and defines the internationalization files for this plugin
- * so that it is ready for translation.
+ * Loads and defines the internationalization files for this plugin so that it 
+ * is ready for translation.
  *
- * @since      1.5.0
- * @since      2.8.0 Renamed class to `Footnotes_i18n`.
- * @package    footnotes
- * @subpackage includes
+ * @link  https://translate.wordpress.org/projects/wp-plugins/footnotes/  GlotPress listing
+ *
+ * @package  footnotes
+ * @subpackage  includes
+ *
+ * @since  1.5.0
+ * @since  2.8.0 Rename class from `Footnotes_Language` to `Footnotes_i18n`.
  */
 class Footnotes_i18n {
 
 	/**
 	 * Load the plugin text domain for translation.
 	 *
-	 * @since    1.5.1
-	 * @since    2.8.0 Rename from `load()` to `load_plugin_textdomain()`. Remove unused `$p_str_language_code` parameter.
+	 * @since  1.5.1
+	 * @since  2.8.0  Rename from `load()` to `load_plugin_textdomain()`. Remove unused `$p_str_language_code` parameter.
 	 */
 	public function load_plugin_textdomain() {
 		load_plugin_textdomain(
diff --git a/src/includes/class-footnotes-loader.php b/src/includes/class-footnotes-loader.php
index b1e652b..efe0dc8 100644
--- a/src/includes/class-footnotes-loader.php
+++ b/src/includes/class-footnotes-loader.php
@@ -1,46 +1,50 @@
 <?php
 /**
- * Register all actions and filters for the plugin.
+ * File providing the `Footnotes_Loader` class.
  *
- * @since      2.8.0
+ * @package footnotes
+ * @subpackage  includes
  *
- * @package    footnotes
- * @subpackage includes
+ * @since 2.8.0
  */
 
 /**
- * Register all actions and filters for the plugin.
+ * Class defining action/filter registration for the plugin.
  *
- * 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.
+ * 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    footnotes
- * @subpackage includes
+ * @package  footnotes
+ * @subpackage  includes
+ *
+ * @since  2.8.0
  */
 class Footnotes_Loader {
 	/**
 	 * The array of actions registered with WordPress.
 	 *
-	 * @since    2.8.0
-	 * @access   protected
-	 * @var      array    $actions    The actions registered with WordPress to fire when the plugin loads.
+	 * @access  protected
+	 * @var  array  $actions  The actions registered with WordPress to fire when the plugin loads.
+	 *
+	 * @since  2.8.0
 	 */
 	protected $actions;
 
 	/**
 	 * The array of filters registered with WordPress.
 	 *
-	 * @since    2.8.0
-	 * @access   protected
-	 * @var      array    $filters    The filters registered with WordPress to fire when the plugin loads.
+	 * @access  protected
+	 * @var  array  $filters  The filters registered with WordPress to fire when the plugin loads.
+	 *
+	 * @since  2.8.0
 	 */
 	protected $filters;
 
 	/**
 	 * Initialize the collections used to maintain the actions and filters.
 	 *
-	 * @since    2.8.0
+	 * @since  2.8.0
 	 */
 	public function __construct() {
 
@@ -52,12 +56,13 @@ class Footnotes_Loader {
 	/**
 	 * Add a new action to the collection to be registered with WordPress.
 	 *
-	 * @since    2.8.0
-	 * @param    string $hook             The name of the WordPress action that is being registered.
-	 * @param    object $component        A reference to the instance of the object on which the action is defined.
-	 * @param    string $callback         The name of the function definition on the $component.
-	 * @param    int    $priority         Optional. The priority at which the function should be fired. Default is 10.
-	 * @param    int    $accepted_args    Optional. The number of arguments that should be passed to the $callback. Default is 1.
+	 * @param  string  $hook  The name of the WordPress action that is being registered.
+	 * @param  object  $component  A reference to the instance of the object on which the action is defined.
+	 * @param  string  $callback  The name of the function definition on the `$component`.
+	 * @param  int  $priority  (optional) The priority at which the function should be fired. Default is 10.
+	 * @param  int  $accepted_args  (optional) The number of arguments that should be passed to the $callback. Default is 1.
+	 *
+	 * @since  2.8.0
 	 */
 	public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
 		$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args );
@@ -66,12 +71,13 @@ class Footnotes_Loader {
 	/**
 	 * Add a new filter to the collection to be registered with WordPress.
 	 *
-	 * @since    2.8.0
-	 * @param    string $hook             The name of the WordPress filter that is being registered.
-	 * @param    object $component        A reference to the instance of the object on which the filter is defined.
-	 * @param    string $callback         The name of the function definition on the $component.
-	 * @param    int    $priority         Optional. The priority at which the function should be fired. Default is 10.
-	 * @param    int    $accepted_args    Optional. The number of arguments that should be passed to the $callback. Default is 1.
+	 * @param  string  $hook  The name of the WordPress filter that is being registered.
+	 * @param  object  $component  A reference to the instance of the object on which the filter is defined.
+	 * @param  string  $callback  The name of the function definition on the `$component`.
+	 * @param  int  $priority  (optional) The priority at which the function should be fired. Default is 10.
+	 * @param  int  $accepted_args  (optional) The number of arguments that should be passed to the $callback. Default is 1.
+	 *
+	 * @since  2.8.0
 	 */
 	public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
 		$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args );
@@ -81,15 +87,16 @@ class Footnotes_Loader {
 	 * A utility function that is used to register the actions and hooks into a single
 	 * collection.
 	 *
-	 * @since    2.8.0
-	 * @access   private
-	 * @param    array  $hooks            The collection of hooks that is being registered (that is, actions or filters).
-	 * @param    string $hook             The name of the WordPress filter that is being registered.
-	 * @param    object $component        A reference to the instance of the object on which the filter is defined.
-	 * @param    string $callback         The name of the function definition on the $component.
-	 * @param    int    $priority         The priority at which the function should be fired.
-	 * @param    int    $accepted_args    The number of arguments that should be passed to the $callback.
-	 * @return   array                                  The collection of actions and filters registered with WordPress.
+	 * @access  private
+	 * @param  array  $hooks  The collection of hooks that is being registered (that is, actions or filters).
+	 * @param  string  $hook  The name of the WordPress filter that is being registered.
+	 * @param  object  $component  A reference to the instance of the object on which the filter is defined.
+	 * @param  string  $callback  The name of the function definition on the `$component`.
+	 * @param  int  $priority  The priority at which the function should be fired.
+	 * @param  int  $accepted_args The number of arguments that should be passed to the `$callback`.
+	 * @return  array  The collection of actions and filters registered with WordPress.
+	 *
+	 * @since  2.8.0
 	 */
 	private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) {
 
@@ -106,9 +113,9 @@ class Footnotes_Loader {
 	}
 
 	/**
-	 * Register the filters and actions with WordPress.
+	 * Registers the filters and actions with WordPress.
 	 *
-	 * @since    2.8.0
+	 * @since  2.8.0
 	 */
 	public function run() {
 
diff --git a/src/includes/class-footnotes-settings.php b/src/includes/class-footnotes-settings.php
index ffe818d..02189ec 100644
--- a/src/includes/class-footnotes-settings.php
+++ b/src/includes/class-footnotes-settings.php
@@ -4,96 +4,103 @@
  *
  * 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  includes
  *
- * @package footnotes
- * @subpackage includes
+ * @since  1.5.0
+ * @since  2.8.0  Rename file from `settings.php` to `class-footnotes-settings.php`.
  */
 
 require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-convert.php';
 
 /**
- * Loads the settings values, sets to default values if undefined.
+ * Class defining configurable plugin settings.
  *
- * @since 1.5.0
+ * @since  1.5.0
  */
 class Footnotes_Settings {
 
 	/**
 	 * Settings container key for the label of the reference container.
 	 *
-	 * @since 1.5.0
-	 * @var str
+	 * @var  str
+	 *
+	 * @since  1.5.0
 	 */
 	const C_STR_REFERENCE_CONTAINER_NAME = 'footnote_inputfield_references_label';
 
 	/**
 	 * Settings container key to collapse the reference container by default.
 	 *
-	 * @since 1.5.0
-	 * @var str
 	 * The string is converted to Boolean false if 'no', true if 'yes'.
-	 * @see Footnotes_Convert::to_bool()
+	 *
+	 * @var  str
+	 *
+	 * @since  1.5.0
+	 * @todo  Refactor to use sane typing.
 	 */
 	const C_STR_REFERENCE_CONTAINER_COLLAPSE = 'footnote_inputfield_collapse_references';
 
 	/**
 	 * Settings container key for the position of the reference container.
 	 *
-	 * @since 1.5.0
-	 * @var str
+	 * @var  str
+	 *
+	 * @since  1.5.0
 	 */
 	const C_STR_REFERENCE_CONTAINER_POSITION = 'footnote_inputfield_reference_container_place';
 
 	/**
 	 * Settings container key for combining identical footnotes.
 	 *
-	 * @since 1.5.0
-	 * @var str
+	 * @var  str
+	 *
+	 * @since  1.5.0
 	 */
 	const C_STR_COMBINE_IDENTICAL_FOOTNOTES = 'footnote_inputfield_combine_identical';
 
 	/**
-	 * Settings container key for the short code of the footnote’s start.
+	 * Settings container key for the short code of the footnote's start.
 	 *
-	 * @since 1.5.0
-	 * @var str
+	 * @var  str
+	 *
+	 * @since  1.5.0
 	 */
 	const C_STR_FOOTNOTES_SHORT_CODE_START = 'footnote_inputfield_placeholder_start';
 
 	/**
-	 * Settings container key for the short code of the footnote’s end.
+	 * Settings container key for the short code of the footnote's end.
 	 *
-	 * @since 1.5.0
-	 * @var str
+	 * @var  str
+	 *
+	 * @since  1.5.0
 	 */
 	const C_STR_FOOTNOTES_SHORT_CODE_END = 'footnote_inputfield_placeholder_end';
 
 	/**
 	 * Settings container key for the user-defined short code of the footnotes start.
 	 *
-	 * @since 1.5.0
-	 * @var str
+	 * @var  str
+	 *
+	 * @since  1.5.0
 	 */
 	const C_STR_FOOTNOTES_SHORT_CODE_START_USER_DEFINED = 'footnote_inputfield_placeholder_start_user_defined';
 
 	/**
 	 * Settings container key for the user-defined short code of the footnotes end.
 	 *
-	 * @since 1.5.0
-	 * @var str
+	 * @var  str
+	 *
+	 * @since  1.5.0
 	 */
 	const C_STR_FOOTNOTES_SHORT_CODE_END_USER_DEFINED = 'footnote_inputfield_placeholder_end_user_defined';
 
 	/**
 	 * Settings container key for the counter style of the footnotes.
 	 *
-	 * @since 1.5.0
-	 * @var str
+	 * @var  str
+	 *
+	 * @since  1.5.0
 	 */
 	const C_STR_FOOTNOTES_COUNTER_STYLE = 'footnote_inputfield_counter_style';
 
diff --git a/src/includes/class-footnotes-template.php b/src/includes/class-footnotes-template.php
index 874fafd..9e20f5a 100644
--- a/src/includes/class-footnotes-template.php
+++ b/src/includes/class-footnotes-template.php
@@ -1,97 +1,93 @@
 <?php
 /**
- * Includes the Template Engine to load and handle all Template files of the Plugin.
+ * File providing the `Footnotes_Template` class.
  *
- * @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 includes
+ * @package  footnotes
+ * @subpackage  includes
+ *
+ * @since  1.5.0
+ * @since  2.2.6  Add support for custom templates in sibling folder.
+ * @since  2.8.0  Rename file from `templates.php` to `class-footnotes-templates.php`.
  */
 
 /**
- * Handles each Template file for the Plugin Frontend (e.g. Settings Dashboard, Public pages, ...).
- * Loads a template file, replaces all Placeholders and returns the replaced file content.
+ * Class defining template rendering.
  *
- * @since 1.5.0
+ * Loads a template file, replaces all Placeholders and returns the replaced 
+ * file content.
+ 
+ * @package  footnotes
+ * @subpackage  includes
+ *
+ * @since  1.5.0
+ * @todo  Refactor templating.
  */
 class Footnotes_Template {
 
 	/**
 	 * Directory name for dashboard partials.
 	 *
-	 * @since 1.5.0
 	 * @var string
+	 *
+	 * @since 1.5.0
 	 */
 	const C_STR_DASHBOARD = 'admin/partials';
 
 	/**
 	 * Directory name for public partials.
 	 *
-	 * @since 1.5.0
 	 * @var string
+	 *
+	 * @since 1.5.0
 	 */
 	const C_STR_PUBLIC = 'public/partials';
 
 	/**
 	 * Contains the content of the template after initialize.
 	 *
-	 * @since  1.5.0
 	 * @var string
+	 *
+	 * @since  1.5.0
 	 */
 	private $a_str_original_content = '';
 
 	/**
 	 * Contains the content of the template after initialize with replaced place holders.
 	 *
-	 * @since  1.5.0
 	 * @var string
+	 *
+	 * @since  1.5.0
 	 */
 	private $a_str_replaced_content = '';
 
 	/**
 	 * Plugin Directory
 	 *
-	 * @since 2.4.0d3
+	 * @var  string
 	 *
-	 * @var string
+	 * @since  2.4.0d3
 	 */
 	public $plugin_directory;
 
 	/**
 	 * Class Constructor. Reads and loads the template file without replace any placeholder.
 	 *
-	 * @since 1.5.0
-	 * @param string $p_str_file_type Template file type (take a look on the Class constants).
-	 * @param string $p_str_file_name Template file name inside the Template directory without the file extension.
-	 * @param string $p_str_extension Optional Template file extension (default: html).
+	 * @param  string  $p_str_file_type  Template file type.
+	 * @param  string  $p_str_file_name  Template file name inside the `partials/` directory, without the file extension.
+	 * @param  string  $p_str_extension  (optional) Template file extension (default: 'html').
 	 *
-	 * - Adding: Templates: support for custom templates in sibling folder, thanks to @misfist issue report.
-	 *
-	 * @since 2.2.6
-	 *
-	 * @reporter @misfist
-	 * @link https://wordpress.org/support/topic/template-override-filter/
+	 * @since  1.5.0
+	 * @todo  Refactor templating.
 	 */
 	public function __construct( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) {
 		// No template file type and/or file name set.
 		if ( empty( $p_str_file_type ) || empty( $p_str_file_name ) ) {
 			return;
 		}
-
-		/**
-		 * Define plugin root path.
-		 *
-		 * @since 2.4.0d3
-		 */
+		
 		$this->plugin_directory = plugin_dir_path( dirname( __FILE__ ) );
-
-		/**
-		 * Modularize functions.
-		 *
-		 * @since 2.4.0d3
-		 */
+		
 		$template = $this->get_template( $p_str_file_type, $p_str_file_name, $p_str_extension );
 		if ( $template ) {
 			$this->process_template( $template );
@@ -104,9 +100,11 @@ class Footnotes_Template {
 	/**
 	 * Replace all placeholders specified in array.
 	 *
+	 * @param  array  $p_arr_placeholders  Placeholders (key = placeholder, value = value).
+	 * @return  bool  `true` on Success, `false` if placeholders invalid.
+	 *
 	 * @since  1.5.0
-	 * @param array $p_arr_placeholders Placeholders (key = placeholder, value = value).
-	 * @return bool True on Success, False if Placeholders invalid.
+	 * @todo  Refactor templating.
 	 */
 	public function replace( $p_arr_placeholders ) {
 		// No placeholders set.
@@ -129,6 +127,7 @@ class Footnotes_Template {
 	 * Reloads the original content of the template file.
 	 *
 	 * @since  1.5.0
+	 * @todo  Refactor templating.
 	 */
 	public function reload() {
 		$this->a_str_replaced_content = $this->a_str_original_content;
@@ -137,8 +136,10 @@ class Footnotes_Template {
 	/**
 	 * Returns the content of the template file with replaced placeholders.
 	 *
+	 * @return  string  Template content with replaced placeholders.
+	 *
 	 * @since  1.5.0
-	 * @return string Template content with replaced placeholders.
+	 * @todo  Refactor templating.
 	 */
 	public function get_content() {
 		return $this->a_str_replaced_content;
@@ -147,16 +148,11 @@ class Footnotes_Template {
 	/**
 	 * Process template file.
 	 *
-	 * @since 2.4.0d3
+	 * @param  string  $template  The template to be processed.
+	 * @return  void
 	 *
-	 * @param string $template The template to be processed.
-	 * @return void
-	 *
-	 * @since 2.0.3  Replace tab with a space.
-	 * @since 2.0.3  Replace 2 spaces with 1.
-	 * @since 2.0.4  Collapse multiple spaces.
-	 * @since 2.2.6  Delete a space before a closing pointy bracket.
-	 * @since 2.5.4  Collapse HTML comments and PHP/JS docblocks (only).
+	 * @since  2.4.0d3
+	 * @todo  Refactor templating.
 	 */
 	public function process_template( $template ) {
 		// phpcs:disable WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
@@ -174,18 +170,13 @@ class Footnotes_Template {
 	/**
 	 * Get the template.
 	 *
-	 * - Adding: Templates: Enable template location stack, thanks to @misfist issue report and code contribution.
+	 * @param  string  $p_str_file_type  The file type of the template.
+	 * @param  string  $p_str_file_name  The file name of the template.
+	 * @param  string  $p_str_extension  The file extension of the template.
+	 * @return  mixed  `false` or the template path
 	 *
-	 * @since 2.4.0d3 Contribution.
-	 * @since 2.5.0   Release.
-	 *
-	 * @contributor @misfist
-	 * @link https://wordpress.org/support/topic/template-override-filter/#post-13864301
-	 *
-	 * @param string $p_str_file_type The file type of the template.
-	 * @param string $p_str_file_name The file name of the template.
-	 * @param string $p_str_extension The file extension of the template.
-	 * @return mixed false | template path
+	 * @since 2.5.0
+	 * @todo  Refactor templating.
 	 */
 	public function get_template( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) {
 		$located = false;
@@ -197,6 +188,8 @@ class Footnotes_Template {
 		 * add_filter( 'footnotes_template_directory', function( $directory ) {
 		 *  return 'template_parts/footnotes/';
 		 * } );
+		 *
+		 * @todo  Review.
 		 */
 		$template_directory = apply_filters( '', 'footnotes/' );
 		$custom_directory   = apply_filters( 'footnotes_custom_template_directory', 'footnotes-custom/' );
diff --git a/src/includes/class-footnotes.php b/src/includes/class-footnotes.php
index 02d7590..313018b 100644
--- a/src/includes/class-footnotes.php
+++ b/src/includes/class-footnotes.php
@@ -1,66 +1,69 @@
 <?php // phpcs:disable PEAR.Commenting.FileComment.Missing
 /**
- * The file that defines the core plugin class
+ * File providing core `Footnotes` class.
  *
  * A class definition that includes attributes and functions used across both the
  * public-facing side of the site and the admin area.
  *
- * @since       1.5.0
- *
- * @package     footnotes
+ * @package  footnotes
  * @subpackage  includes
+ *
+ * @since  1.5.0
+ * @since  2.8.0  Rename file from `init.php` to `class-footnotes.php`.
  */
 
 /**
- * The core plugin class.
+ * Class providing core plugin functionality.
  *
  * This is used to define internationalization, admin-specific hooks, and
  * public-facing site hooks.
- *
- * Also maintains the unique identifier of this plugin as well as the current
- * version of the plugin.
- *
- * @since 1.5.0
- * @package     footnotes
+ 
+ * @package  footnotes
  * @subpackage  includes
+ *
+ * @since  1.5.0
+ * @since  2.8.0
  */
 class Footnotes {
 	/**
 	 * The loader that's responsible for maintaining and registering all hooks that power
 	 * the plugin.
 	 *
-	 * @since    2.8.0
-	 * @access   protected
-	 * @var      Footnotes_Loader    $loader    Maintains and registers all hooks for the plugin.
+	 * @access  protected
+	 * @var  Footnotes_Loader  $loader  Maintains and registers all hooks for the plugin.
+	 *
+	 * @since  2.8.0
 	 */
 	protected $loader;
 
 	/**
 	 * The unique identifier of this plugin
 	 *
-	 * @since    2.8.0
-	 * @access   protected
-	 * @var      string    $plugin_name    The string used to uniquely identify this plugin.
+	 * @since  2.8.0
+	 * @access  protected
+	 * @var  string  $plugin_name  The string used to uniquely identify this plugin.
 	 */
 	protected $plugin_name;
 
 	/**
 	 * The current version of the plugin.
 	 *
-	 * @since    2.8.0
-	 * @access   protected
-	 * @var      string    $version    The current version of the plugin.
+	 * @since  2.8.0
+	 * @access  protected
+	 * @var  string  $version  The current version of the plugin.
 	 */
 	protected $version;
 
 	/**
-	 * Define the core functionality of the plugin.
+	 * Build the core of the plugin.
 	 *
-	 * Set the plugin name and the plugin version that can be used throughout the plugin.
-	 * Load the dependencies, define the locale, and set the hooks for the admin area and
-	 * the public-facing side of the site.
+	 * Set the plugin name and the plugin version that can be used throughout the
+	 * plugin. Load the dependencies, define the locale, and set the hooks for 
+	 * the admin area and the public-facing side of the site.
 	 *
-	 * @since    1.0.0
+	 * @uses  PLUGIN_VERSION  The plugin version constant.
+	 *
+	 * @since  1.0.0
 	 */
 	public function __construct() {
 		if ( defined( 'PLUGIN_VERSION' ) ) {
@@ -80,7 +83,7 @@ class Footnotes {
 	/**
 	 * Load the required dependencies for this plugin.
 	 *
-	 * Include the following files that make up the plugin:
+	 * Includes the following files that make up the plugin:
 	 *
 	 * - `Footnotes_Loader`. Orchestrates the hooks of the plugin.
 	 * - `Footnotes_i18n`. Defines internationalization functionality.
@@ -91,11 +94,13 @@ class Footnotes {
 	 * - `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
+	 * Creates an instance of the loader which will be used to register the hooks
 	 * with WordPress.
 	 *
-	 * @since    2.8.0
-	 * @access   private
+	 * @access  private
+	 * @uses  Footnotes_Loader  Loads plugin dependencies.
+	 *
+	 * @since  2.8.0
 	 */
 	private function load_dependencies() {
 
@@ -137,11 +142,13 @@ class Footnotes {
 	/**
 	 * Define the locale for this plugin for internationalization.
 	 *
-	 * Uses the `Footnotes_i18n` class in order to set the domain and to register the hook
-	 * with WordPress.
+	 * Uses the {@see Footnotes_i18n} class in order to set the domain and to 
+	 * register the hook with WordPress.
 	 *
-	 * @since    2.8.0
-	 * @access   private
+	 * @access  private
+	 * @uses  Footnotes_i18n  Handles initialization functions.
+	 *
+	 * @since  2.8.0
 	 */
 	private function set_locale() {
 
@@ -152,12 +159,14 @@ class Footnotes {
 	}
 
 	/**
-	 * Register all of the hooks related to the admin area functionality
-	 * of the plugin.
+	 * Register all of the hooks related to the admin area functionality of the 
+	 * plugin.
 	 *
-	 * @since 1.5.0
-	 * @since 2.8.0 Moved registrating from various classes into `Footnotes_Admin`.
-	 * @access private
+	 * @access  private
+	 * @uses  Footnotes_Admin  Defines admin functionality.
+	 *
+	 * @since  1.5.0
+	 * @since  2.8.0 Moved hook registrations from various classes into `Footnotes_Admin`.
 	 */
 	private function define_admin_hooks() {
 
@@ -182,11 +191,13 @@ class Footnotes {
 	}
 
 	/**
-	 * Register all of the hooks related to the public-facing functionality
-	 * of the plugin.
+	 * Register all of the hooks related to the public-facing functionality of 
+	 * the plugin.
 	 *
-	 * @since    2.8.0
 	 * @access   private
+	 * @uses  Footnotes_Admin  Defines public-facing functionality.
+	 *
+	 * @since  2.8.0
 	 */
 	private function define_public_hooks() {
 
@@ -199,42 +210,43 @@ class Footnotes {
 	}
 
 	/**
-	 * Run the loader to execute all of the hooks with WordPress.
+	 * Runs the loader to execute all of the hooks with WordPress.
 	 *
-	 * @since 1.5.0
-	 *
-	 * @see self::initialize_widgets()
+	 * @since  1.5.0
 	 */
 	public function run() {
 		$this->loader->run();
 	}
 
 	/**
-	 * The name of the plugin used to uniquely identify it within the context of
-	 * WordPress and to define internationalization functionality.
+	 * Gets the name of the plugin used to uniquely identify it within the 
+	 * context of WordPress and to define internationalization functionality.
 	 *
-	 * @since     1.0.0
-	 * @return    string    The name of the plugin.
+	 * @return  string  The name of the plugin.
+	 *
+	 * @since  2.8.0
 	 */
 	public function get_plugin_name() {
 		return $this->plugin_name;
 	}
 
 	/**
-	 * The reference to the class that orchestrates the hooks with the plugin.
+	 * Returns a reference to the class that orchestrates the hooks with the plugin.
 	 *
-	 * @since     1.0.0
-	 * @return    Footnotes_Loader    Orchestrates the hooks of the plugin.
+	 * @return  Footnotes_Loader  Orchestrates the hooks of the plugin.
+	 *
+	 * @since  2.8.0
 	 */
 	public function get_loader() {
 		return $this->loader;
 	}
 
 	/**
-	 * Retrieve the version number of the plugin.
+	 * Gets the version number of the plugin.
 	 *
-	 * @since     1.0.0
-	 * @return    string    The version number of the plugin.
+	 * @return  string  The version number of the plugin.
+	 *
+	 * @since  2.8.0
 	 */
 	public function get_version() {
 		return $this->version;