diff --git a/src/admin/layout/class-engine.php b/src/admin/layout/class-engine.php index 212513e..534da19 100644 --- a/src/admin/layout/class-engine.php +++ b/src/admin/layout/class-engine.php @@ -121,7 +121,7 @@ abstract class Engine { * @param string $p_str_title Title of the section. * @param int $p_int_settings_container_index Settings Container index. * @param bool $p_bool_has_submit_button Whether a ‘Submit’ button should - * be displayed for this section. Default `true`. + * be displayed for this section. Default `true`. * @return array { * A dashboard section. * diff --git a/src/admin/layout/class-settings.php b/src/admin/layout/class-settings.php index 923d618..88beb58 100644 --- a/src/admin/layout/class-settings.php +++ b/src/admin/layout/class-settings.php @@ -77,8 +77,7 @@ class Settings extends Engine { /** * Returns an array of all registered sections for the sub-page. * - * @see Engine::add_section() For more information on the - * section array format. + * @see Engine::add_section() For more information on the section array format. * @return array[] All of the registered sections. * * @since 1.5.0 diff --git a/src/includes/class-convert.php b/src/includes/class-convert.php index 02509e7..2ceed93 100644 --- a/src/includes/class-convert.php +++ b/src/includes/class-convert.php @@ -22,16 +22,16 @@ class Convert { * * @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. + * @return string The index converted to the defined counter style. * * @since 1.5.0 */ - public static function index( $p_int_index, $p_str_convert_style = 'arabic_plain' ) { + public static function index( int $p_int_index, string $p_str_convert_style = 'arabic_plain' ): string { switch ( $p_str_convert_style ) { - case 'romanic': - return self::to_romanic( $p_int_index, true ); + case 'roman': + return self::to_roman( $p_int_index, true ); case 'roman_low': - return self::to_romanic( $p_int_index, false ); + return self::to_roman( $p_int_index, false ); case 'latin_high': return self::to_latin( $p_int_index, true ); case 'latin_low': @@ -57,7 +57,7 @@ class Convert { * @since 1.0-gamma * @todo Replace with built-in char casting. */ - private static function to_latin( $p_int_value, $p_bool_upper_case ) { + private static function to_latin( int $p_int_value, bool $p_bool_upper_case ): string { // Output string. $l_str_return = ''; $l_int_offset = 0; @@ -89,7 +89,7 @@ class Convert { * @since 1.0-gamma * @todo Replace with built-in string formatting. */ - private static function to_arabic_leading( $p_int_value ) { + private static function to_arabic_leading( int $p_int_value ): string { // Add a leading 0 if number lower then 10. if ( $p_int_value < 10 ) { return '0' . $p_int_value; @@ -106,9 +106,9 @@ class Convert { * * @since 1.0-gamma */ - private static function to_romanic( $p_int_value, $p_bool_upper_case ) { - // Table containing all necessary romanic letters. - $l_arr_romanic_letters = array( + private static function to_roman( int $p_int_value, bool $p_bool_upper_case ): string { + // Table containing all necessary roman letters. + $l_arr_roman_numerals = array( 'M' => 1000, 'CM' => 900, 'D' => 500, @@ -127,15 +127,15 @@ class Convert { $l_str_return = ''; // Iterate through integer value until it is reduced to 0. while ( $p_int_value > 0 ) { - foreach ( $l_arr_romanic_letters as $l_str_romanic => $l_int_arabic ) { + foreach ( $l_arr_roman_numerals as $l_str_roman => $l_int_arabic ) { if ( $p_int_value >= $l_int_arabic ) { $p_int_value -= $l_int_arabic; - $l_str_return .= $l_str_romanic; + $l_str_return .= $l_str_roman; break; } } } - // Return romanic letters as string. + // Return roman letters as string. if ( $p_bool_upper_case ) { return strtoupper( $l_str_return ); } @@ -151,7 +151,7 @@ class Convert { * @since 1.0-beta * @todo Replace with built-in type casting. */ - public static function to_bool( $p_str_value ) { + public static function to_bool( string $p_str_value ): bool { // Convert string to lower-case to make it easier. $p_str_value = strtolower( $p_str_value ); // Check if string seems to contain a "true" value. @@ -171,12 +171,13 @@ class Convert { * Get an HTML array short code depending on Arrow-Array key index. * * @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. + * @return string|string[] Array of all arrows if index is empty, otherwise HTML tag of a specific arrow. * * @since 1.3.2 * @todo Review. + * @todo Single return type. */ - public static function get_arrow( $p_int_index = -1 ) { + public static function get_arrow( int $p_int_index = -1 ) { // Define all possible arrows. $l_arr_arrows = array( '↑', '↥', '↟', '↩', '↲', '↵', '⇑', '⇡', '⇧', '￪' ); // Convert index to an integer. @@ -196,6 +197,7 @@ class Convert { * Displays a variable. * * @param mixed $p_mixed_value The variable to display. + * @return void * * @since 1.5.0 * @todo Replace with proper logging/debug functions. diff --git a/src/includes/class-deactivator.php b/src/includes/class-deactivator.php index ab0f437..8c2aa9a 100644 --- a/src/includes/class-deactivator.php +++ b/src/includes/class-deactivator.php @@ -24,6 +24,8 @@ class Deactivator { * Currently NOP. * * @since 2.8.0 + * + * @return void */ public static function deactivate() { // Nothing yet. diff --git a/src/includes/class-i18n.php b/src/includes/class-i18n.php index 4f04184..4d7a2fd 100644 --- a/src/includes/class-i18n.php +++ b/src/includes/class-i18n.php @@ -31,6 +31,8 @@ class i18n { * * @since 1.5.1 * @since 2.8.0 Rename from `load()` to `load_plugin_textdomain()`. Remove unused `$p_str_language_code` parameter. + * + * @return void */ public function load_plugin_textdomain() { load_plugin_textdomain( diff --git a/src/includes/class-loader.php b/src/includes/class-loader.php index 428c7e5..62915b6 100644 --- a/src/includes/class-loader.php +++ b/src/includes/class-loader.php @@ -24,20 +24,20 @@ class Loader { /** * The array of actions registered with WordPress. * - * @access protected - * @var array $actions The actions registered with WordPress to fire when the plugin loads. - * * @since 2.8.0 + * @see Loader::add() For more information on the hook array format. + * + * @var (string|int|object)[][] $actions The actions registered with WordPress to fire when the plugin loads. */ protected $actions; /** * The array of filters registered with WordPress. * - * @access protected - * @var array $filters The filters registered with WordPress to fire when the plugin loads. - * * @since 2.8.0 + * @see Loader::add() For more information on the hook array format. + * + * @var (string|int|object)[][] $filters The filters registered with WordPress to fire when the plugin loads. */ protected $filters; @@ -45,6 +45,8 @@ class Loader { * Initialize the collections used to maintain the actions and filters. * * @since 2.8.0 + * + * @return void */ public function __construct() { @@ -56,13 +58,15 @@ class Loader { /** * Add a new action to the collection to be registered with WordPress. * + * @since 2.8.0 + * @see Loader::add() For more information on the hook array format. + * * @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 + * @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. + * @return void */ public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) { $this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args ); @@ -71,13 +75,15 @@ class Loader { /** * Add a new filter to the collection to be registered with WordPress. * + * @since 2.8.0 + * @see Loader::add() For more information on the hook array format. + * * @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 + * @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. + * @return void */ public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) { $this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args ); @@ -87,16 +93,23 @@ class Loader { * A utility function that is used to register the actions and hooks into a single * collection. * - * @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 + * + * @param (string|int|object)[][] $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 (string|int|object)[][] { + * The registered hook(s). + * + * @type string $hook The name of the registered WordPress hook. + * @type object $component A reference to the instance of the object on which the hook is defined. + * @type string $callback The name of the function definition on the `$component`. + * @type int $priority The priority at which the function should be fired. + * @type int $accepted_args The number of arguments that should be passed to the `$callback`. + * } */ private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) { @@ -116,6 +129,9 @@ class Loader { * Registers the filters and actions with WordPress. * * @since 2.8.0 + * @see Loader::add() For more information on the hook array format. + * + * @return void */ public function run() { diff --git a/src/includes/class-template.php b/src/includes/class-template.php index 7ed5f89..86f8edb 100644 --- a/src/includes/class-template.php +++ b/src/includes/class-template.php @@ -30,59 +30,60 @@ class Template { /** * Directory name for dashboard partials. * - * @var string - * * @since 1.5.0 + * + * @var string */ const C_STR_DASHBOARD = 'admin/partials'; /** * Directory name for public partials. * - * @var string - * * @since 1.5.0 + * + * @var string */ const C_STR_PUBLIC = 'public/partials'; /** * Contains the content of the template after initialize. * - * @var string - * * @since 1.5.0 + * + * @var string */ private $a_str_original_content = ''; /** * Contains the content of the template after initialize with replaced place holders. * - * @var string - * * @since 1.5.0 + * + * @var string */ private $a_str_replaced_content = ''; /** * Plugin Directory * - * @var string - * * @since 2.4.0d3 + * + * @var string */ public $plugin_directory; /** * Class Constructor. Reads and loads the template file without replace any placeholder. * + * @since 1.5.0 + * @todo Refactor templating. + * * @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'). - * - * @since 1.5.0 - * @todo Refactor templating. + * @return void */ - public function __construct( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) { + public function __construct( string $p_str_file_type, string $p_str_file_name, string $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; @@ -102,13 +103,13 @@ class 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 * @todo Refactor templating. + * + * @param string[] $p_arr_placeholders Placeholders (key = placeholder, value = value). + * @return bool `true` on Success, `false` if placeholders invalid. */ - public function replace( $p_arr_placeholders ) { + public function replace( array $p_arr_placeholders ): bool { // No placeholders set. if ( empty( $p_arr_placeholders ) ) { return false; @@ -130,6 +131,8 @@ class Template { * * @since 1.5.0 * @todo Refactor templating. + * + * @return void */ public function reload() { $this->a_str_replaced_content = $this->a_str_original_content; @@ -138,25 +141,25 @@ class Template { /** * Returns the content of the template file with replaced placeholders. * - * @return string Template content with replaced placeholders. - * * @since 1.5.0 * @todo Refactor templating. + * + * @return string Template content with replaced placeholders. */ - public function get_content() { + public function get_content(): string { return $this->a_str_replaced_content; } /** * Process template file. * - * @param string $template The template to be processed. - * @return void - * * @since 2.4.0d3 * @todo Refactor templating. + * + * @param string $template The template to be processed. + * @return void */ - public function process_template( $template ) { + public function process_template( string $template ) { // phpcs:disable WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents $this->a_str_original_content = preg_replace( '##s', '', file_get_contents( $template ) ); // phpcs:enable @@ -172,52 +175,43 @@ class Template { /** * Get the template. * + * @since 2.5.0 + * @todo Refactor templating. + * @todo Single return type. + * * @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.5.0 - * @todo Refactor templating. + * @return string|bool `false` or the template path */ - public function get_template( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) { + public function get_template( string $p_str_file_type, string $p_str_file_name, string $p_str_extension = 'html' ) { $located = false; - /** + /* * The directory can be changed. * - * @usage to change location of templates to 'template_parts/footnotes/': - * add_filter( 'template_directory', function( $directory ) { - * return 'template_parts/footnotes/'; - * } ); - * - * @todo Review. + * To change location of templates to 'template_parts/footnotes/': + * add_filter( 'template_directory', function( $directory ) { + * return 'template_parts/footnotes/'; + * } ); */ $template_directory = apply_filters( '', 'footnotes/' ); $custom_directory = apply_filters( 'custom_template_directory', 'footnotes-custom/' ); $template_name = $p_str_file_type . '/' . $p_str_file_name . '.' . $p_str_extension; - /** - * Look in active theme. - */ + // Look in active theme. if ( file_exists( trailingslashit( get_stylesheet_directory() ) . $template_directory . $template_name ) ) { $located = trailingslashit( get_stylesheet_directory() ) . $template_directory . $template_name; - /** - * Look in parent theme in case active is child. - */ + // Look in parent theme in case active is child. } elseif ( file_exists( trailingslashit( get_template_directory() ) . $template_directory . $template_name ) ) { $located = trailingslashit( get_template_directory() ) . $template_directory . $template_name; - /** - * Look in custom plugin directory. - */ + // Look in custom plugin directory. } elseif ( file_exists( trailingslashit( WP_PLUGIN_DIR ) . $custom_directory . 'templates/' . $template_name ) ) { $located = trailingslashit( WP_PLUGIN_DIR ) . $custom_directory . 'templates/' . $template_name; - /** - * Fall back to the templates shipped with the plugin. - */ + // Fall back to the templates shipped with the plugin. } elseif ( file_exists( $this->plugin_directory . $template_name ) ) { $located = $this->plugin_directory . $template_name; }