Rumperuu/footnotes
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: update docblocks

Browse source
This commit is contained in:
Ben Goldsworthy 2021-04-27 08:31:37 +01:00
parent 332f4b8284
commit 100a815cd5
11 changed files with 64 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
src/admin/class-footnotes-admin.php
View file

@ -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();

5
src/admin/layout/class-footnotes-layout-init.php
View file

@ -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';

6
src/admin/layout/class-footnotes-layout-settings.php
View file

@ -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';

6
src/includes/class-footnotes-config.php
View file

@ -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
*/
/**

6
src/includes/class-footnotes-convert.php
View file

@ -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
*/
/**

9
src/includes/class-footnotes-settings.php
View file

@ -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';

6
src/includes/class-footnotes-template.php
View file

@ -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
*/
/**

17
src/includes/class-footnotes.php
View file

@ -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';

51
src/public/class-footnotes-public.php
View file

@ -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' );

6
src/public/widget/class-footnotes-widget-base.php
View file

@ -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
*/
/**

7
src/public/widget/class-footnotes-widget-reference-container.php
View file

@ -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.