refactor: add type decs

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

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
+	 * @see  Engine::add_section()  For more information on the section array format.
-	 *                                                                                     section array format.
 	 * @return  array[]  All of the registered sections.
 	 *
 	 * @since  1.5.0

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':
+			case 'roman':
-				return self::to_romanic( $p_int_index, true );
+				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 ) {
+	private static function to_roman( int $p_int_value, bool $p_bool_upper_case ): string {
-		// Table containing all necessary romanic letters.
+		// Table containing all necessary roman letters.
-		$l_arr_romanic_letters = array(
+		$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( '&#8593;', '&#8613;', '&#8607;', '&#8617;', '&#8626;', '&#8629;', '&#8657;', '&#8673;', '&#8679;', '&#65514;' );
 		// 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.

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.

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(

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    $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  int    $accepted_args  Optional. The number of arguments that should be passed to the $callback. Default is 1.
-	 *
+	 * @return void
-	 * @since  2.8.0
 	 */
 	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    $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  int    $accepted_args  Optional. The number of arguments that should be passed to the $callback. Default is 1.
-	 *
+	 * @return void
-	 * @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 );
@@ -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() {
 

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').
-	 *
+	 * @return void
-	 * @since  1.5.0
-	 * @todo  Refactor templating.
 	 */
-	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
+	 * @return  string|bool  `false` or the 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' ) {
+	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/':
+		 * To change location of templates to 'template_parts/footnotes/':
-		 * add_filter( 'template_directory', function( $directory ) {
+		 *     add_filter( 'template_directory', function( $directory ) {
-		 *  return 'template_parts/footnotes/';
+		 *         return 'template_parts/footnotes/';
-		 * } );
+		 *     } );
-		 *
-		 * @todo  Review.
 		 */
 		$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;
 		}