docs: extend PHPDocs and fix some minor code style issues

src/Admin/CommentsColumns.php

@@ -2,7 +2,7 @@
 /**
  * Class registering columns for the "spam comments view".
  *
- * @package AntispamBee\Helpers
+ * @package AntispamBee\Admin
  */
 
 namespace AntispamBee\Admin;
@@ -93,6 +93,7 @@ public static function print_plugin_column( $column, $comment_id ) {
 		$reasons      = explode( ',', $spam_reason );
 		$reason_texts = SpamReasonTextHelper::get_texts_by_slugs( $reasons );
 
+		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- reason texts pre-sanitized.
 		echo implode( ',<br>', $reason_texts );
 	}
 

src/Admin/DashboardWidgets.php

@@ -74,6 +74,12 @@ private static function get_spam_count() {
 		return self::format_number( $count );
 	}
 
+	/**
+	 * Format a number.
+	 *
+	 * @param float $number Number to format.
+	 * @return string
+	 */
 	private static function format_number( $number ) {
 		return ( get_locale() === 'de_DE' ? number_format( $number, 0, '', '.' ) : number_format_i18n( $number ) );
 	}

src/Admin/Fields/Checkbox.php

@@ -17,6 +17,8 @@ class Checkbox extends Field implements RenderElement {
 	 * Get HTML.
 	 */
 	public function render() {
+		// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
+
 		$label = ! empty( $this->get_label() ) ? sprintf(
 			'<label for="%s">%s</label>',
 			esc_attr( $this->get_name() ),

src/Admin/Fields/CheckboxGroup.php

@@ -1,18 +1,25 @@
 <?php
+/**
+ * The Checkbox Field group for the admin UI.
+ *
+ * @package AntispamBee\Admin\Fields
+ */
 
 namespace AntispamBee\Admin\Fields;
 
 use AntispamBee\Admin\RenderElement;
 use AntispamBee\Helpers\Settings;
 
 /**
- * Checkbox field.
+ * Checkbox group.
  */
 class CheckboxGroup extends Field implements RenderElement {
 	/**
 	 * Render HTML.
 	 */
 	public function render() {
+		// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
+
 		$options = isset( $this->option['options'] ) ? $this->option['options'] : [];
 		if ( ! is_array( $options ) ) {
 			return;
@@ -38,6 +45,8 @@ public function render() {
 	/**
 	 * Get Value.
 	 *
+	 * @param string $key Option key.
+	 *
 	 * @return mixed Value stored in database.
 	 */
 	protected function get_custom_value( $key ) {

src/Admin/Fields/Field.php

@@ -30,6 +30,8 @@ abstract class Field {
 
 	/**
 	 * Type of controllable.
+	 *
+	 * @var string
 	 */
 	protected $controllable_option_name;
 
@@ -123,7 +125,7 @@ protected function maybe_show_description() {
 	/**
 	 * Get HTML for field.
 	 *
-	 * @return string Elment HTML.
+	 * @return string Element HTML.
 	 */
 	abstract public function render();
 }

src/Admin/Fields/Inline.php

@@ -1,12 +1,27 @@
 <?php
+/**
+ * The inline input field for the admin UI.
+ *
+ * @package AntispamBee\Admin\Fields
+ */
 
 namespace AntispamBee\Admin\Fields;
 
 use AntispamBee\Admin\RenderElement;
 
+/**
+ * Inline input field.
+ */
 class Inline extends Field implements RenderElement {
 
+	/**
+	 * Get HTML for field.
+	 *
+	 * @return string Element HTML.
+	 */
 	public function render() {
+		// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
+
 		if ( ! $this->option['input'] instanceof Field ) {
 			echo '';
 

src/Admin/Fields/Select.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * The Select Field for the admin UI.
+ *
+ * @package AntispamBee\Admin\Fields
+ */
 
 namespace AntispamBee\Admin\Fields;
 
@@ -13,6 +18,8 @@ class Select extends Field implements RenderElement {
 	 * Get HTML.
 	 */
 	public function render() {
+		// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
+
 		$name     = $this->get_name();
 		$multiple = isset( $this->option['multiple'] ) && $this->option['multiple'] ? 'multiple' : '';
 		echo "<select name='$name' $multiple>";

src/Admin/Fields/Text.php

@@ -14,8 +14,18 @@
  */
 class Text extends Field implements RenderElement {
 
+	/**
+	 * Placeholder string.
+	 *
+	 * @var string
+	 */
 	protected $placeholder;
 
+	/**
+	 * Get placeholder.
+	 *
+	 * @return string
+	 */
 	public function get_placeholder() {
 		return $this->placeholder;
 	}
@@ -24,6 +34,8 @@ public function get_placeholder() {
 	 * Get HTML.
 	 */
 	public function render() {
+		// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
+
 		printf(
 			'<p><label for="%s">%s</label></p><p>%s</p>',
 			esc_attr( $this->get_name() ),
@@ -33,6 +45,11 @@ public function render() {
 		$this->maybe_show_description();
 	}
 
+	/**
+	 * Get HTML markup for the actual input field.
+	 *
+	 * @return string
+	 */
 	public function get_injectable_markup() {
 		return sprintf(
 			'<input type="%1$s" id="%2$s" name="%2$s" value="%3$s" class="%4$s" placeholder="%5$s">',
@@ -44,6 +61,11 @@ public function get_injectable_markup() {
 		);
 	}
 
+	/**
+	 * Get element class(es).
+	 *
+	 * @return string
+	 */
 	protected function get_class() {
 		$classes    = [
 			'small'   => 'small-text',
@@ -58,6 +80,11 @@ protected function get_class() {
 		return 'regular-text';
 	}
 
+	/**
+	 * Get type of input field.
+	 *
+	 * @return string
+	 */
 	protected function get_type() {
 		return isset( $this->option['input_type'] ) ? $this->option['input_type'] : 'text';
 	}

src/Admin/Fields/Textarea.php

@@ -17,6 +17,8 @@ class Textarea extends Field implements RenderElement {
 	 * Render HTML.
 	 */
 	public function render() {
+		// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
+
 		printf(
 			'<p><label for="%1$s">%2$s</label></p><p><textarea name="%1$s" id="%1$s" placeholder="%4$s">%3$s</textarea></p>',
 			esc_attr( $this->get_name() ),

src/Admin/Section.php

@@ -55,11 +55,6 @@ class Section {
 	 */
 	private $type;
 
-	/**
-	 *
-	 * @var Controllable[]
-	 */
-	private $controllables;
 
 	/**
 	 * Initializing Tab.
@@ -76,12 +71,24 @@ public function __construct( $slug, $title, $description = '', $type = null ) {
 		$this->type        = $type;
 	}
 
+	/**
+	 * Add controllable items to section.
+	 *
+	 * @param array|null $controllables List of controllable items to add.
+	 * @return void
+	 */
 	public function add_controllables( $controllables ) {
 		if ( ! empty( $controllables ) ) {
 			$this->generate_fields( $controllables );
 		}
 	}
 
+	/**
+	 * Generate settings fields for a list of controllable items.
+	 *
+	 * @param Controllable[] $controllables List of controllable items to add.
+	 * @return void
+	 */
 	private function generate_fields( $controllables ) {
 		foreach ( $controllables as $controllable ) {
 			$label       = $controllable::get_label();
@@ -103,7 +110,7 @@ private function generate_fields( $controllables ) {
 			if ( ! empty( $options ) ) {
 				foreach ( $options as $option ) {
 					$valid_for = isset( $option['valid_for'] ) ? $option['valid_for'] : null;
-					if ( $valid_for !== null && $this->type !== $valid_for ) {
+					if ( null !== $valid_for && $this->type !== $valid_for ) {
 						continue;
 					}
 					$fields[] = $this->generate_field( $option, $controllable );
@@ -117,6 +124,13 @@ private function generate_fields( $controllables ) {
 		}
 	}
 
+	/**
+	 * Generate field for a controllable item's option.
+	 *
+	 * @param array        $option       Option name.
+	 * @param Controllable $controllable Controllable item.
+	 * @return Checkbox|CheckboxGroup|Inline|Select|Text|Textarea|null
+	 */
 	private function generate_field( $option, $controllable ) {
 		switch ( $option['type'] ) {
 			case 'input':
@@ -215,14 +229,14 @@ function () use ( $row ) {
 	/**
 	 * Renders the fields for a row.
 	 *
-	 * @param array $row
+	 * @param array $row Row of fields.
 	 */
 	protected function render_row_fields( $row ) {
 		foreach ( $row['fields'] as $key => $field ) {
 			$field->render();
 
 			// Add linebreak after field if not (last and not checkbox without label).
-			if ( $key !== count( $row['fields'] ) - 1 ) {
+			if ( ( count( $row['fields'] ) - 1 ) !== $key ) {
 				if ( $field instanceof Checkbox && empty( $field->get_label() ) ) {
 					continue;
 				}

src/Admin/SettingsPage.php

@@ -35,11 +35,15 @@ class SettingsPage {
 	private $tabs = [];
 
 	/**
+	 * List of controllable rules.
+	 *
 	 * @var Rules[]
 	 */
 	private $rules = [];
 
 	/**
+	 * List of controllable post processors
+	 *
 	 * @var PostProcessors[]
 	 */
 	private $post_processors = [];
@@ -59,7 +63,7 @@ public function init() {
 		add_action( 'admin_init', [ $this, 'setup_settings' ] );
 
 		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
-		$this->active_tab = isset( $_GET['tab'] ) ? $_GET['tab'] : 'general';
+		$this->active_tab = isset( $_GET['tab'] ) ? sanitize_key( wp_unslash( $_GET['tab'] ) ) : 'general';
 	}
 
 	/**
@@ -79,14 +83,16 @@ public function add_menu() {
 	 * Setup tabs content.
 	 */
 	public function setup_settings() {
-		// Todo: Add a way to build rows and fields with a fluent interface? (Nice-to-have)
+		// Todo: Add a way to build rows and fields with a fluent interface? (Nice-to-have).
+
 		/*
 		 * Todo: Instead of using an array to pass options to a function, one could introduce a class that contains
 		 *   these options as class attributes. You instantiate an object of this class and pass it to the
 		 *   Components::filter() method. For frequently used options, one could also use blueprints for options.
 		 *   This would make refactoring easier, but would slightly increase the complexity. (nice-to-have).
 		 */
-		// Todo: Fix the confusing naming. We have a lot of type e.g. (Nice-to-have)
+
+		// Todo: Fix the confusing naming. We have a lot of type e.g. (Nice-to-have).
 
 		$tabs['general'] = new Tab(
 			'general',
@@ -114,7 +120,7 @@ public function setup_settings() {
 
 		$this->populate_tabs();
 
-		// Register option setting
+		// Register option setting.
 		foreach ( $this->tabs as $tab ) {
 			foreach ( $tab->get_sections() as $section ) {
 				if ( $tab->get_slug() !== $this->active_tab ) {
@@ -134,6 +140,11 @@ public function setup_settings() {
 		);
 	}
 
+	/**
+	 * Populate settings tabs.
+	 *
+	 * @return void
+	 */
 	protected function populate_tabs() {
 		$type = $this->active_tab;
 

src/Admin/Tab.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * Settings tab model.
+ *
+ * @package AntispamBee\Admin
+ */
 
 namespace AntispamBee\Admin;
 
@@ -30,8 +35,8 @@ class Tab {
 	/**
 	 * Initialize the tab.
 	 *
-	 * @param string    $slug Title for tab
-	 * @param string    $title Title for tab
+	 * @param string    $slug Title for tab.
+	 * @param string    $title Title for tab.
 	 * @param Section[] $sections Sections object array.
 	 */
 	public function __construct( $slug, $title, $sections = [] ) {
@@ -67,6 +72,12 @@ public function get_sections() {
 		return $this->sections;
 	}
 
+	/**
+	 * Add a section to the settings tab.
+	 *
+	 * @param Section $section Section to add.
+	 * @return void
+	 */
 	public function add_section( Section $section ) {
 		$this->sections[] = $section;
 	}