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 = 'footnotes'; /** - * 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;