Skip to content

Docs: Restore the @return tag for WP_Duotone::is_preset() - #12791

Open
jigneshbhavani wants to merge 1 commit into
WordPress:trunkfrom
jigneshbhavani:fix/64896-duotone-is-preset-docblock
Open

Docs: Restore the @return tag for WP_Duotone::is_preset()#12791
jigneshbhavani wants to merge 1 commit into
WordPress:trunkfrom
jigneshbhavani:fix/64896-duotone-is-preset-docblock

Conversation

@jigneshbhavani

Copy link
Copy Markdown

WP_Duotone::is_preset() carries two @param tags for the same variable, giving contradictory types, and documents no return value at all:

 * @param string $duotone_attr The duotone attribute from a block.
 * @param string|string[] $duotone_attr The duotone attribute from a block.
 */
private static function is_preset( $duotone_attr ) {

In [61603] the type was widened from string to string|string[], but the new tag replaced the @return line rather than the old @param:

-	 * @return bool True if the duotone preset present and valid.
+	 * @param string|string[] $duotone_attr The duotone attribute from a block.

So the method lost its return documentation and kept a stale parameter type in the same edit.

Fix

Drop the stale @param and restore the @return. The wording is the one [61603] removed, so nothing here is invented. Two independent references confirm it:

  • WP_Duotone::get_slug_from_attribute(), immediately above, was updated by that same changeset and got it right: @param string|string[] and a @return.
  • The Gutenberg counterpart, lib/class-wp-duotone-gutenberg.php, still reads @param string|string[] $duotone_attr and @return bool True if the duotone preset present and valid.

string|string[] is the correct type. The method guards with ! is_string( $duotone_attr ) and returns false, which is exactly the array case [61603] was written to handle.

No functional change. phpcs passes on the file.

Trac ticket: https://core.trac.wordpress.org/ticket/64896

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Scanning src/ for docblock and signature disagreements, which is how this was found, and drafting this description. I confirmed the cause in the changeset history, checked the wording against the sibling method and the Gutenberg copy, ran phpcs, and I take responsibility for the change.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

In r61603 the `@param` type for `$duotone_attr` was widened from `string` to `string|string[]`, but the new tag replaced the `@return` line instead of the old `@param`. That left the method with two `@param` tags for the same variable, giving contradictory types, and no documented return value at all.

Restore the `@return` and drop the stale `@param`. The wording is the one r61603 removed, and matches the sibling `WP_Duotone::get_slug_from_attribute()`, which the same changeset updated correctly.

No functional change.

Follow-up to r56101, r61603.

See #64896.
@github-actions

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props bejignesh.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@github-actions

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant