Merge pull request #353 from Yoast/JRF/docs-various-updates

Docs: various updates

admin-functions.php

@@ -20,13 +20,17 @@
 
 /**
  * Wrapper for the option 'duplicate_post_version'.
+ *
+ * @return mixed
  */
 function duplicate_post_get_installed_version() {
 	return get_option( 'duplicate_post_version' );
 }
 
 /**
  * Wrapper for the defined constant DUPLICATE_POST_CURRENT_VERSION.
+ *
+ * @return string
  */
 function duplicate_post_get_current_version() {
 	return DUPLICATE_POST_CURRENT_VERSION;
@@ -36,6 +40,8 @@ function duplicate_post_get_current_version() {
 
 /**
  * Adds handlers depending on the options.
+ *
+ * @return void
  */
 function duplicate_post_admin_init() {
 	duplicate_post_plugin_upgrade();
@@ -76,6 +82,8 @@ function duplicate_post_admin_init() {
 
 /**
  * Plugin upgrade.
+ *
+ * @return void
  */
 function duplicate_post_plugin_upgrade() {
 	$installed_version = duplicate_post_get_installed_version();
@@ -203,6 +211,8 @@ function duplicate_post_migrate_show_links_in_options( $defaults ) {
  * Shows the welcome notice.
  *
  * @global string $wp_version The WordPress version string.
+ *
+ * @return void
  */
 function duplicate_post_show_update_notice() {
 	if ( ! current_user_can( 'manage_options' ) ) {
@@ -268,6 +278,8 @@ function duplicate_post_dismiss_notice() {
  *
  * @param int     $new_id New post ID.
  * @param WP_Post $post   The original post object.
+ *
+ * @return void
  */
 function duplicate_post_copy_post_taxonomies( $new_id, $post ) {
 	global $wpdb;
@@ -316,6 +328,8 @@ function duplicate_post_copy_post_taxonomies( $new_id, $post ) {
  *
  * @param int     $new_id The new post ID.
  * @param WP_Post $post   The original post object.
+ *
+ * @return void
  */
 function duplicate_post_copy_post_meta_info( $new_id, $post ) {
 	$post_meta_keys = get_post_custom_keys( $post->ID );
@@ -425,6 +439,8 @@ function duplicate_post_wp_slash( $value ) {
  *
  * @param int     $new_id The new post ID.
  * @param WP_Post $post   The original post object.
+ *
+ * @return void
  */
 function duplicate_post_copy_attachments( $new_id, $post ) {
 	// Get thumbnail ID.
@@ -489,6 +505,8 @@ function duplicate_post_copy_attachments( $new_id, $post ) {
  * @param int     $new_id The new post ID.
  * @param WP_Post $post   The original post object.
  * @param string  $status Optional. The destination status.
+ *
+ * @return void
  */
 function duplicate_post_copy_children( $new_id, $post, $status = '' ) {
 	// Get children.
@@ -514,6 +532,8 @@ function duplicate_post_copy_children( $new_id, $post, $status = '' ) {
  *
  * @param int     $new_id The new post ID.
  * @param WP_Post $post   The original post object.
+ *
+ * @return void
  */
 function duplicate_post_copy_comments( $new_id, $post ) {
 	$comments = get_comments(
@@ -737,9 +757,9 @@ function duplicate_post_create_duplicate( $post, $status = '', $parent_id = '' )
 /**
  * Adds some links on the plugin page.
  *
- * @param array  $links The links array.
- * @param string $file  The file name.
- * @return array
+ * @param array<string> $links The links array.
+ * @param string        $file  The file name.
+ * @return array<string>
  */
 function duplicate_post_add_plugin_links( $links, $file ) {
 	if ( plugin_basename( __DIR__ . '/duplicate-post.php' ) === $file ) {

common-functions.php

@@ -63,6 +63,8 @@ function duplicate_post_get_clone_post_link( $id = 0, $context = 'display', $dra
  * @param string      $before Optional. Display before edit link.
  * @param string      $after  Optional. Display after edit link.
  * @param int         $id     Optional. Post ID.
+ *
+ * @return void
  */
 function duplicate_post_clone_post_link( $link = null, $before = '', $after = '', $id = 0 ) {
 	$post = get_post( $id );

compat/jetpack-functions.php

@@ -10,6 +10,8 @@
 
 /**
  * Add handlers for JetPack compatibility.
+ *
+ * @return void
  */
 function duplicate_post_jetpack_init() {
 	add_filter( 'duplicate_post_excludelist_filter', 'duplicate_post_jetpack_add_to_excludelist', 10, 1 );
@@ -39,6 +41,8 @@ function duplicate_post_jetpack_add_to_excludelist( $meta_excludelist ) {
  * Disable Markdown.
  *
  * To be called before copy.
+ *
+ * @return void
  */
 function duplicate_post_jetpack_disable_markdown() {
 	WPCom_Markdown::get_instance()->unload_markdown_for_posts();
@@ -48,6 +52,8 @@ function duplicate_post_jetpack_disable_markdown() {
  * Enaable Markdown.
  *
  * To be called after copy.
+ *
+ * @return void
  */
 function duplicate_post_jetpack_enable_markdown() {
 	WPCom_Markdown::get_instance()->load_markdown_for_posts();

compat/wpml-functions.php

@@ -12,6 +12,8 @@
 
 /**
  * Add handlers for WPML compatibility.
+ *
+ * @return void
  */
 function duplicate_post_wpml_init() {
 	if ( defined( 'ICL_SITEPRESS_VERSION' ) ) {
@@ -35,6 +37,8 @@ function duplicate_post_wpml_init() {
  * @param int     $post_id ID of the copy.
  * @param WP_Post $post    Original post object.
  * @param string  $status  Status of the new post.
+ *
+ * @return void
  */
 function duplicate_post_wpml_copy_translations( $post_id, $post, $status = '' ) {
 	global $sitepress;
@@ -78,6 +82,8 @@ function duplicate_post_wpml_copy_translations( $post_id, $post, $status = '' )
  * Duplicate string packages.
  *
  * @global array() $duplicated_posts Array of duplicated posts.
+ *
+ * @return void
  */
 function duplicate_wpml_string_packages() { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals -- Reason: renaming the function would be a BC-break.
 	global $duplicated_posts;

duplicate-post.php

@@ -68,6 +68,8 @@
  * @phpcs:disable PHPCompatibility.FunctionNameRestrictions.ReservedFunctionNames.FunctionDoubleUnderscore
  * @phpcs:disable WordPress.NamingConventions.ValidFunctionName.FunctionDoubleUnderscore
  * @phpcs:disable WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound
+ *
+ * @return void
  */
 function __duplicate_post_main() {
 	new Duplicate_Post();
@@ -76,6 +78,8 @@ function __duplicate_post_main() {
 
 /**
  * Initialises the internationalisation domain.
+ *
+ * @return void
  */
 function duplicate_post_load_plugin_textdomain() {
 	load_plugin_textdomain( 'duplicate-post', false, basename( __DIR__ ) . '/languages/' );

src/admin/options-form-generator.php

@@ -127,8 +127,8 @@ public function sort_taxonomy_objects( $taxonomy1, $taxonomy2 ) {
 	/**
 	 * Extracts and formats the description associated with the input field.
 	 *
-	 * @param string|array $description The description string. Can be an array of strings.
-	 * @param string       $id          The ID of the input field.
+	 * @param string|array<string> $description The description string. Can be an array of strings.
+	 * @param string               $id          The ID of the input field.
 	 *
 	 * @return string The description HTML for the input.
 	 */

src/post-duplicator.php

@@ -15,7 +15,7 @@ class Post_Duplicator {
 	/**
 	 * Returns an array with the default option values.
 	 *
-	 * @return array The default options values.
+	 * @return array<string, bool|int|string|array|null> The default options values.
 	 */
 	public function get_default_options() {
 		return [

src/ui/block-editor.php

@@ -223,7 +223,7 @@ public function get_original_post_edit_url() {
 	 *
 	 * @param WP_Post $post The current post object.
 	 *
-	 * @return array The data to pass to JavaScript.
+	 * @return array<string, mixed> The data to pass to JavaScript.
 	 */
 	protected function generate_js_object( WP_Post $post ) {
 		$is_rewrite_and_republish_copy = $this->permissions_helper->is_rewrite_and_republish_copy( $post );

src/ui/newsletter.php

@@ -69,7 +69,7 @@ public static function newsletter_signup_form() {
 	/**
 	 * Handles and validates Newsletter form.
 	 *
-	 * @return array|null
+	 * @return array<string, string>|null
 	 */
 	private static function newsletter_handle_form() {
 
@@ -105,7 +105,7 @@ private static function newsletter_handle_form() {
 	 *
 	 * @param string $email Subscriber email.
 	 *
-	 * @return array Feedback response.
+	 * @return array<string, string> Feedback response.
 	 */
 	private static function newsletter_subscribe_to_mailblue( $email ) {
 		$response = \wp_remote_post(

src/utils.php

@@ -177,7 +177,7 @@ public static function get_roles() {
 	/**
 	 * Gets the default meta field names to be filtered out.
 	 *
-	 * @return array The names of the meta fields to filter out by default.
+	 * @return array<string> The names of the meta fields to filter out by default.
 	 */
 	public static function get_default_filtered_meta_names() {
 		return [

tests/Unit/Admin/Options_Form_Generator_Test.php

@@ -32,6 +32,8 @@ final class Options_Form_Generator_Test extends TestCase {
 
 	/**
 	 * Sets the instance.
+	 *
+	 * @return void
 	 */
 	protected function set_up() {
 		parent::set_up();
@@ -76,6 +78,8 @@ protected function set_up() {
 	 * Tests the constructor of the class.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::__construct
+	 *
+	 * @return void
 	 */
 	public function test_constructor() {
 		$this->instance->__construct( $this->options_inputs );
@@ -90,6 +94,8 @@ public function test_constructor() {
 	 * Tests the generation of options input elements.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::generate_options_input
+	 *
+	 * @return void
 	 */
 	public function test_generate_options_input_generated_output() {
 		$this->options_inputs->allows(
@@ -134,6 +140,8 @@ public function test_generate_options_input_generated_output() {
 	 * Tests the calling of the correct methods when generating inputs.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::generate_options_input
+	 *
+	 * @return void
 	 */
 	public function test_generate_options_input_calls_expected_methods() {
 		$options = [
@@ -178,6 +186,8 @@ public function test_generate_options_input_calls_expected_methods() {
 	 * Tests the skipping of generation of options input elements when the option is empty.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::generate_options_input
+	 *
+	 * @return void
 	 */
 	public function test_dont_generate_options_input_from_empty_options() {
 		$options = [
@@ -191,6 +201,8 @@ public function test_dont_generate_options_input_from_empty_options() {
 	 * Tests the skipping of generation of option input elements when the WordPress version isn't high enough.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::generate_options_input
+	 *
+	 * @return void
 	 */
 	public function test_dont_generate_options_input_for_invalid_version() {
 		$options = [
@@ -230,6 +242,8 @@ public function test_dont_generate_options_input_for_invalid_version() {
 	 * Tests the generation of sub option input elements.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::generate_options_input
+	 *
+	 * @return void
 	 */
 	public function test_generate_options_input_for_suboptions() {
 		$options = [
@@ -264,6 +278,8 @@ static function ( $checked, $current = true ) {
 	 * Tests the extraction of descriptions.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::extract_description
+	 *
+	 * @return void
 	 */
 	public function test_extract_description() {
 		$this->assertSame(
@@ -292,6 +308,8 @@ public function test_extract_description() {
 	 * Tests the generate_taxonomy_exclusion_list callback method.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::generate_taxonomy_exclusion_list
+	 *
+	 * @return void
 	 */
 	public function test_generate_taxonomy_exclusion_list() {
 		$labels1       = new stdClass();
@@ -362,6 +380,8 @@ static function ( $checked, $current = true ) {
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::generate_roles_permission_list
 	 * @runInSeparateProcess
 	 * @preserveGlobalState disabled
+	 *
+	 * @return void
 	 */
 	public function test_generate_roles_permission_list() {
 		$this->stub_wp_roles();
@@ -396,6 +416,8 @@ static function ( $checked, $current = true ) {
 	 * Tests the generate_post_types_list callback method.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::generate_post_types_list
+	 *
+	 * @return void
 	 */
 	public function test_generate_post_types_list() {
 		$this->instance
@@ -438,10 +460,12 @@ static function ( $checked, $current = true ) {
 	 * @dataProvider is_checked_provider
 	 * @covers       \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::is_checked
 	 *
-	 * @param string $option        The option name.
-	 * @param array  $option_values The option values.
-	 * @param string $parent_option The parent option.
-	 * @param array  $assertion     The assumed assertion values.
+	 * @param string               $option        The option name.
+	 * @param array<string, mixed> $option_values The option values.
+	 * @param string               $parent_option The parent option.
+	 * @param array<string, mixed> $assertion     The assumed assertion values.
+	 *
+	 * @return void
 	 */
 	public function test_is_checked( $option, $option_values, $parent_option, $assertion = [] ) {
 		if ( $assertion['expected'] === false ) {
@@ -467,7 +491,7 @@ public function test_is_checked( $option, $option_values, $parent_option, $asser
 	/**
 	 * Provides the test_is_checked test with data to use in the tests.
 	 *
-	 * @return array The data to run the test against.
+	 * @return array<array<string|array<string, mixed>>> The data to run the test against.
 	 */
 	public static function is_checked_provider() {
 		return [
@@ -505,6 +529,8 @@ public static function is_checked_provider() {
 	 * Tests the prepare_input_id helper method.
 	 *
 	 * @covers \Yoast\WP\Duplicate_Post\Admin\Options_Form_Generator::prepare_input_id
+	 *
+	 * @return void
 	 */
 	public function test_prepare_input_id() {
 		$this->assertSame( 'my-form-element-id', $this->instance->prepare_input_id( 'my_form_element_id' ) );