From 100a815cd5106501fd87f49ec575aba941ca270a Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Tue, 27 Apr 2021 08:31:37 +0100 Subject: [PATCH] docs: update docblocks --- src/admin/class-footnotes-admin.php | 12 +++-- .../layout/class-footnotes-layout-init.php | 5 +- .../class-footnotes-layout-settings.php | 6 +-- src/includes/class-footnotes-config.php | 6 +-- src/includes/class-footnotes-convert.php | 6 +-- src/includes/class-footnotes-settings.php | 9 ++-- src/includes/class-footnotes-template.php | 6 +-- src/includes/class-footnotes.php | 17 +++++-- src/public/class-footnotes-public.php | 51 ++++++------------- .../widget/class-footnotes-widget-base.php | 6 +-- ...s-footnotes-widget-reference-container.php | 7 +-- 11 files changed, 64 insertions(+), 67 deletions(-) diff --git a/src/admin/class-footnotes-admin.php b/src/admin/class-footnotes-admin.php index 687b7c2..0eb8fe0 100644 --- a/src/admin/class-footnotes-admin.php +++ b/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_Layout_Settings`. TODO + * - `Footnotes_WYSIWYG`. Provides plugin integration with the WYSIWYG editor. + * - `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(); diff --git a/src/admin/layout/class-footnotes-layout-init.php b/src/admin/layout/class-footnotes-layout-init.php index 9d2ed4e..94150ed 100644 --- a/src/admin/layout/class-footnotes-layout-init.php +++ b/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'; diff --git a/src/admin/layout/class-footnotes-layout-settings.php b/src/admin/layout/class-footnotes-layout-settings.php index d25293d..b606b71 100644 --- a/src/admin/layout/class-footnotes-layout-settings.php +++ b/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'; diff --git a/src/includes/class-footnotes-config.php b/src/includes/class-footnotes-config.php index 192cfc8..2440fa8 100644 --- a/src/includes/class-footnotes-config.php +++ b/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 */ /** diff --git a/src/includes/class-footnotes-convert.php b/src/includes/class-footnotes-convert.php index 47cf84b..2cfda17 100644 --- a/src/includes/class-footnotes-convert.php +++ b/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 */ /** diff --git a/src/includes/class-footnotes-settings.php b/src/includes/class-footnotes-settings.php index 1eb7f3f..b93f4cb 100644 --- a/src/includes/class-footnotes-settings.php +++ b/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'; diff --git a/src/includes/class-footnotes-template.php b/src/includes/class-footnotes-template.php index 5860833..5f6088e 100644 --- a/src/includes/class-footnotes-template.php +++ b/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 */ /** diff --git a/src/includes/class-footnotes.php b/src/includes/class-footnotes.php index a6f4769..14ae38a 100644 --- a/src/includes/class-footnotes.php +++ b/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_i18n. Defines internationalization functionality. - * - Footnotes_Admin. Defines all hooks for the admin area. - * - Footnotes_Public. Defines all hooks for the public side of the site. + * - `Footnotes_Loader`. Orchestrates the hooks of the plugin. + * - `Footnotes_i18n`. Defines internationalization functionality. + * - `Footnotes_Config`. Defines plugin details. + * - `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'; diff --git a/src/public/class-footnotes-public.php b/src/public/class-footnotes-public.php index 05bb174..3067ef2 100644 --- a/src/public/class-footnotes-public.php +++ b/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' ); diff --git a/src/public/widget/class-footnotes-widget-base.php b/src/public/widget/class-footnotes-widget-base.php index 9dded2a..84a8926 100644 --- a/src/public/widget/class-footnotes-widget-base.php +++ b/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 */ /** diff --git a/src/public/widget/class-footnotes-widget-reference-container.php b/src/public/widget/class-footnotes-widget-reference-container.php index d9b8e65..f12a181 100644 --- a/src/public/widget/class-footnotes-widget-reference-container.php +++ b/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.