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 @@
foot';
/**
- * 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 = '';
/**
- * 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 = '♥';
/**
- * 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 = '';
/**
- * 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 @@
';
}
- // 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 @@
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 @@
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 @@
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;