Merge pull request #140 from Yoast/JRF/Docs/various-improvements

Docs: various improvements

src/Whip_Host.php

@@ -40,6 +40,7 @@ public static function name() {
 	 * In a non-WordPress content this function just returns the passed name.
 	 *
 	 * @param string $name The current name of the host.
+	 *
 	 * @return string The filtered name of the host.
 	 */
 	private static function filterName( $name ) {
@@ -96,6 +97,7 @@ public static function hostingPageUrl() {
 	 * In a non-WordPress context this function just returns a link to the Yoast hosting page.
 	 *
 	 * @param string $url The previous URL.
+	 *
 	 * @return string The new URL to the hosting overview page.
 	 */
 	private static function filterHostingPageUrl( $url ) {

src/Whip_MessageDismisser.php

@@ -20,7 +20,7 @@ class Whip_MessageDismisser {
 	/**
 	 * The current time.
 	 *
-	 * @var string
+	 * @var int
 	 */
 	protected $currentTime;
 
@@ -46,6 +46,8 @@ public function __construct( $currentTime, $threshold, Whip_DismissStorage $stor
 
 	/**
 	 * Saves the version number to the storage to indicate the message as being dismissed.
+	 *
+	 * @return void
 	 */
 	public function dismiss() {
 		$this->storage->set( $this->currentTime );

src/Whip_MessageFormatter.php

@@ -14,6 +14,7 @@ final class Whip_MessageFormatter {
 	 * Wraps a piece of text in HTML strong tags.
 	 *
 	 * @param string $toWrap The text to wrap.
+	 *
 	 * @return string The wrapped text.
 	 */
 	public static function strong( $toWrap ) {
@@ -24,6 +25,7 @@ public static function strong( $toWrap ) {
 	 * Wraps a piece of text in HTML p tags.
 	 *
 	 * @param string $toWrap The text to wrap.
+	 *
 	 * @return string The wrapped text.
 	 */
 	public static function paragraph( $toWrap ) {
@@ -34,6 +36,7 @@ public static function paragraph( $toWrap ) {
 	 * Wraps a piece of text in HTML p and strong tags.
 	 *
 	 * @param string $toWrap The text to wrap.
+	 *
 	 * @return string The wrapped text.
 	 */
 	public static function strongParagraph( $toWrap ) {

src/Whip_MessagesManager.php

@@ -23,6 +23,8 @@ public function __construct() {
 	 * Adds a message to the Messages Manager.
 	 *
 	 * @param Whip_Message $message The message to add.
+	 *
+	 * @return void
 	 */
 	public function addMessage( Whip_Message $message ) {
 		$whipVersion = require __DIR__ . '/configs/version.php';
@@ -50,6 +52,8 @@ public function listMessages() {
 
 	/**
 	 * Deletes all messages.
+	 *
+	 * @return void
 	 */
 	public function deleteMessages() {
 		unset( $GLOBALS['whip_messages'] );

src/Whip_RequirementsChecker.php

@@ -57,6 +57,8 @@ public function __construct( $configuration = array(), $textdomain = 'default' )
 	 * Adds a requirement to the list of requirements if it doesn't already exist.
 	 *
 	 * @param Whip_Requirement $requirement The requirement to add.
+	 *
+	 * @return void
 	 */
 	public function addRequirement( Whip_Requirement $requirement ) {
 		// Only allow unique entries to ensure we're not checking specific combinations multiple times.
@@ -122,6 +124,8 @@ private function requirementIsFulfilled( Whip_Requirement $requirement ) {
 
 	/**
 	 * Checks if all requirements are fulfilled and adds a message to the message manager if necessary.
+	 *
+	 * @return void
 	 */
 	public function check() {
 		foreach ( $this->requirements as $requirement ) {
@@ -140,6 +144,8 @@ public function check() {
 	 * Adds a message to the message manager for requirements that cannot be fulfilled.
 	 *
 	 * @param Whip_Requirement $requirement The requirement that cannot be fulfilled.
+	 *
+	 * @return void
 	 */
 	private function addMissingRequirementMessage( Whip_Requirement $requirement ) {
 		switch ( $requirement->component() ) {

src/Whip_VersionRequirement.php

@@ -111,6 +111,8 @@ public static function fromCompareString( $component, $comparisonString ) {
 	 * @param string $version   The component version.
 	 * @param string $operator  The operator to use when comparing version.
 	 *
+	 * @return void
+	 *
 	 * @throws Whip_EmptyProperty       When any of the parameters is empty.
 	 * @throws Whip_InvalidOperatorType When the $operator parameter is invalid.
 	 * @throws Whip_InvalidType         When any of the parameters is not of the expected type.

src/facades/wordpress.php

@@ -10,6 +10,8 @@
 	 * Facade to quickly check if version requirements are met.
 	 *
 	 * @param array $requirements The requirements to check.
+	 *
+	 * @return void
 	 */
 	function whip_wp_check_versions( $requirements ) {
 		// Only show for admin users.

src/interfaces/Whip_MessagePresenter.php

@@ -12,6 +12,8 @@ interface Whip_MessagePresenter {
 
 	/**
 	 * Renders the message.
+	 *
+	 * @return void
 	 */
 	public function renderMessage();
 }

src/messages/Whip_BasicMessage.php

@@ -42,6 +42,8 @@ public function body() {
 	 *
 	 * @param string $body Message body.
 	 *
+	 * @return void
+	 *
 	 * @throws Whip_EmptyProperty When the $body parameter is empty.
 	 * @throws Whip_InvalidType   When the $body parameter is not of the expected type.
 	 */

src/presenters/Whip_WPMessagePresenter.php

@@ -48,6 +48,8 @@ public function __construct( Whip_Message $message, Whip_MessageDismisser $dismi
 	 * Registers hooks to WordPress.
 	 *
 	 * This is a separate function so you can control when the hooks are registered.
+	 *
+	 * @return void
 	 */
 	public function registerHooks() {
 		add_action( 'admin_notices', array( $this, 'renderMessage' ) );
@@ -58,6 +60,8 @@ public function registerHooks() {
 	 *
 	 * @deprecated 1.2.0 Use the Whip_WPMessagePresenter::registerHooks() method instead.
 	 * @codeCoverageIgnore
+	 *
+	 * @return void
 	 * @phpcs:disable Generic.NamingConventions.CamelCapsFunctionName
 	 */
 	public function register_hooks() {
@@ -67,6 +71,8 @@ public function register_hooks() {
 
 	/**
 	 * Renders the messages present in the global to notices.
+	 *
+	 * @return void
 	 */
 	public function renderMessage() {
 		$dismissListener = new Whip_WPMessageDismissListener( $this->dismisser );

tests/ConfigurationTest.php

@@ -14,6 +14,8 @@ class ConfigurationTest extends Whip_TestCase {
 	 * Tests the creation of a Whip_Configuration with invalid input.
 	 *
 	 * @covers Whip_Configuration::__construct
+	 *
+	 * @return void
 	 */
 	public function testItThrowsAnErrorIfAFaultyConfigurationIsPassed() {
 		$this->expectExceptionHelper( 'Whip_InvalidType', 'Configuration should be of type array. Found string.' );
@@ -25,6 +27,8 @@ public function testItThrowsAnErrorIfAFaultyConfigurationIsPassed() {
 	 * Tests if Whip_Configuration correctly returns -1 when passed an unknown requirement.
 	 *
 	 * @covers Whip_Configuration::configuredVersion
+	 *
+	 * @return void
 	 */
 	public function testItReturnsANegativeNumberIfRequirementCannotBeFound() {
 		$configuration = new Whip_Configuration( array( 'php' => '5.6' ) );
@@ -44,6 +48,8 @@ public function testItReturnsANegativeNumberIfRequirementCannotBeFound() {
 	 * Tests if Whip_Configuration correctly returns the version number when passed a valid requirement.
 	 *
 	 * @covers Whip_Configuration::configuredVersion
+	 *
+	 * @return void
 	 */
 	public function testItReturnsAnEntryIfRequirementIsFound() {
 		$configuration = new Whip_Configuration( array( 'php' => '5.6' ) );
@@ -63,6 +69,8 @@ public function testItReturnsAnEntryIfRequirementIsFound() {
 	 * Tests if hasRequirementConfigures correctly returns true/false when called with valid/invalid values.
 	 *
 	 * @covers Whip_Configuration::hasRequirementConfigured
+	 *
+	 * @return void
 	 */
 	public function testIfRequirementIsConfigured() {
 		$configuration = new Whip_Configuration( array( 'php' => '5.6' ) );

tests/MessageDismisserTest.php

@@ -15,6 +15,8 @@ class MessageDismisserTest extends Whip_TestCase {
 	 *
 	 * @covers Whip_MessageDismisser::__construct
 	 * @covers Whip_MessageDismisser::dismiss
+	 *
+	 * @return void
 	 */
 	public function testDismiss() {
 		$currentTime = time();
@@ -39,6 +41,8 @@ public function testDismiss() {
 	 * @param int  $savedTime   The saved time.
 	 * @param int  $currentTime The current time.
 	 * @param bool $expected    The expected value.
+	 *
+	 * @return void
 	 */
 	public function testIsDismissibleWithVersions( $savedTime, $currentTime, $expected ) {
 		$storage = new Whip_DismissStorageMock();
@@ -51,7 +55,7 @@ public function testIsDismissibleWithVersions( $savedTime, $currentTime, $expect
 	/**
 	 * Provides array with test values.
 	 *
-	 * @return array[]
+	 * @return array<string, array<int|bool>>
 	 */
 	public function versionNumbersProvider() {
 		return array(

tests/MessageTest.php

@@ -14,6 +14,8 @@ class MessageTest extends Whip_TestCase {
 	 * Tests if Whip_BasicMessage correctly handles a string for its body argument.
 	 *
 	 * @covers Whip_BasicMessage::body
+	 *
+	 * @return void
 	 */
 	public function testMessageHasBody() {
 		$message = new Whip_BasicMessage( 'This is a message' );
@@ -25,6 +27,8 @@ public function testMessageHasBody() {
 	 * Tests if an Exception is correctly thrown when an empty string is passed as argument.
 	 *
 	 * @covers Whip_BasicMessage::validateParameters
+	 *
+	 * @return void
 	 */
 	public function testMessageCannotBeEmpty() {
 		$this->expectExceptionHelper( 'Whip_EmptyProperty', 'Message body cannot be empty.' );
@@ -36,6 +40,8 @@ public function testMessageCannotBeEmpty() {
 	 * Tests if an Exception is correctly thrown when an invalid type is passed as argument.
 	 *
 	 * @covers Whip_BasicMessage::validateParameters
+	 *
+	 * @return void
 	 */
 	public function testMessageMustBeString() {
 		$this->expectExceptionHelper( 'Whip_InvalidType', 'Message body should be of type string. Found integer.' );

tests/MessagesManagerTest.php

@@ -15,6 +15,8 @@ class MessagesManagerTest extends Whip_TestCase {
 	 * without a message, true when given a message.
 	 *
 	 * @covers Whip_MessagesManager::hasMessages
+	 *
+	 * @return void
 	 */
 	public function testHasMessages() {
 		$manager = new Whip_MessagesManager();

tests/RequirementsCheckerTest.php

@@ -15,6 +15,8 @@ class RequirementsCheckerTest extends Whip_TestCase {
 	 *
 	 * @covers Whip_RequirementsChecker::addRequirement
 	 * @covers Whip_RequirementsChecker::totalRequirements
+	 *
+	 * @return void
 	 */
 	public function testItReceivesAUsableRequirementObject() {
 		$checker = new Whip_RequirementsChecker();
@@ -29,6 +31,8 @@ public function testItReceivesAUsableRequirementObject() {
 	 *
 	 * @covers   Whip_RequirementsChecker::addRequirement
 	 * @requires PHP 7
+	 *
+	 * @return void
 	 */
 	public function testItThrowsAnTypeErrorWhenInvalidRequirementIsPassed() {
 		if ( version_compare( phpversion(), '7.0', '<' ) ) {
@@ -52,6 +56,8 @@ public function testItThrowsAnTypeErrorWhenInvalidRequirementIsPassed() {
 	 * Tests if Whip_RequirementsChecker throws an error when passed an invalid requirement.
 	 *
 	 * @covers Whip_RequirementsChecker::addRequirement
+	 *
+	 * @return void
 	 */
 	public function testItThrowsAnTypeErrorWhenInvalidRequirementIsPassedInPHP5() {
 		if ( version_compare( phpversion(), '7.0', '>=' ) ) {
@@ -76,6 +82,8 @@ public function testItThrowsAnTypeErrorWhenInvalidRequirementIsPassedInPHP5() {
 	 *
 	 * @covers Whip_RequirementsChecker::addRequirement
 	 * @covers Whip_RequirementsChecker::totalRequirements
+	 *
+	 * @return void
 	 */
 	public function testItOnlyContainsUniqueComponents() {
 		$checker = new Whip_RequirementsChecker();
@@ -97,6 +105,8 @@ public function testItOnlyContainsUniqueComponents() {
 	 *
 	 * @covers Whip_RequirementsChecker::addRequirement
 	 * @covers Whip_RequirementsChecker::requirementExistsForComponent
+	 *
+	 * @return void
 	 */
 	public function testIfRequirementExists() {
 		$checker = new Whip_RequirementsChecker();
@@ -117,6 +127,8 @@ public function testIfRequirementExists() {
 	 * @covers Whip_RequirementsChecker::check
 	 * @covers Whip_RequirementsChecker::hasMessages
 	 * @covers Whip_RequirementsChecker::getMostRecentMessage
+	 *
+	 * @return void
 	 */
 	public function testCheckIfPHPRequirementIsNotFulfilled() {
 		$checker = new Whip_RequirementsChecker( array( 'php' => 4 ) );
@@ -149,6 +161,8 @@ public function testCheckIfPHPRequirementIsNotFulfilled() {
 	 * @covers Whip_RequirementsChecker::addRequirement
 	 * @covers Whip_RequirementsChecker::check
 	 * @covers Whip_RequirementsChecker::getMostRecentMessage
+	 *
+	 * @return void
 	 */
 	public function testCheckIfRequirementIsFulfilled() {
 		$checker = new Whip_RequirementsChecker( array( 'php' => phpversion() ) );
@@ -168,6 +182,8 @@ public function testCheckIfRequirementIsFulfilled() {
 	 * @covers Whip_RequirementsChecker::check
 	 * @covers Whip_RequirementsChecker::getMostRecentMessage
 	 * @covers Whip_RequirementsChecker::hasMessages
+	 *
+	 * @return void
 	 */
 	public function testCheckIfRequirementIsNotFulfilled() {
 		$checker = new Whip_RequirementsChecker( array( 'mysql' => 4 ) );
@@ -192,6 +208,8 @@ public function testCheckIfRequirementIsNotFulfilled() {
 	 * @covers Whip_RequirementsChecker::addRequirement
 	 * @covers Whip_RequirementsChecker::check
 	 * @covers Whip_RequirementsChecker::hasMessages
+	 *
+	 * @return void
 	 */
 	public function testCheckIfRequirementIsFulfilledWithSpecificComparison() {
 		$checker = new Whip_RequirementsChecker( array( 'php' => 4 ) );
@@ -208,6 +226,8 @@ public function testCheckIfRequirementIsFulfilledWithSpecificComparison() {
 	 * @covers Whip_RequirementsChecker::addRequirement
 	 * @covers Whip_RequirementsChecker::check
 	 * @covers Whip_RequirementsChecker::hasMessages
+	 *
+	 * @return void
 	 */
 	public function testCheckIfRequirementIsNotFulfilledWithSpecificComparison() {
 		$checker = new Whip_RequirementsChecker( array( 'php' => 4 ) );

tests/TestCase.php

@@ -24,7 +24,7 @@ class Whip_TestCase extends PHPUnit_Framework_TestCase {
 	 * cross-version compatible manner.
 	 *
 	 * @param string          $exception The class name of the exception to expect.
-	 * @param string|null     $message   Optional. The exception message to expect.
+	 * @param string          $message   Optional. The exception message to expect.
 	 * @param int|string|null $code      Optional. The exception code to expect.
 	 *
 	 * @return void