Make WordPress Core

Opened 4 months ago

Closed 5 weeks ago

#65259 closed defect (bug) (fixed)

Docs: Fix inline comment typos in build_query_vars_from_query_block() in blocks.php

Reported by: deepakrohilla Owned by: westonruter
Priority: normal Milestone: 7.1
Component: Editor Version: 6.5
Severity: normal Keywords: has-patch
Cc: Focuses: docs

Description (last modified by sabernhardt)

In src/wp-includes/blocks.php, the inline comment inside build_query_vars_from_query_block() contains two errors:

  1. "before hand" should be "beforehand" (compound adverb)
  2. "It detects when a path to file was provided...": from this "It" should be removed.

WordPress inline documentation standards, especially for DocBlocks.
In WordPress coding standards:
The description section should continue naturally and should not start with “It”.

Change History (7)

#2 @westonruter
4 months ago

  • Component GeneralEditor
  • Milestone Awaiting Review7.1
  • Owner set to westonruter
  • Status assignedreviewing
  • Version trunk6.5

#3 @sabernhardt
4 months ago

  • Description modified (diff)
  • r48141 included sentences starting with "It detects" for the function summaries of register_block_script_handle() and register_block_style_handle() (in WordPress 5.5).
  • r55447 added the comment with "before hand" (WP 6.2).
  • r57565 added register_block_script_module_id() (WP 6.5). In addition to starting the second sentence with "It detects", the summary includes "under with" ("under" was not removed).

#4 @adrianduffell
6 weeks ago

It looks like the PR has approval. Is this ready to commit?

#5 @deepakrohilla
5 weeks ago

Yes it's ready to commit.

@westonruter commented on PR #11851:


5 weeks ago
#6

Note: Ignore the changes I've made outside of src/wp-includes/blocks.php. I'll commit those separately. As part of reviewing the docs, I've been improving the documented types for the touched functions.

#7 @westonruter
5 weeks ago

  • Resolutionfixed
  • Status reviewingclosed

In 62966:

Docs: Improve block asset registration docblocks.

Per the inline documentation standards, a docblock's summary belongs on its own line separated from the description, and the description should not open with "It". This is applied to register_block_script_module_id(), register_block_script_handle(), and register_block_style_handle(), together with some missing articles in the same descriptions.

Two of those descriptions no longer matched the code. register_block_script_handle() said the script is registered under an automatically generated handle, but since 6.5.0 the handle is taken from the asset file whenever one provides it, and generation is only the fallback. register_block_style_handle() said it returns the unprocessed style handle otherwise, which does not hold for the first style of a core block: that one is registered from the block's own stylesheet when separate core block assets are loaded, and skipped entirely when they are not.

The same functions gain @phpstan- annotations describing the shape of the $metadata they accept and the narrower strings they return. The shapes follow the block.json schema, which constrains only name, so the remaining fields stay plain strings; file is nullable and name optional because register_block_type_from_metadata() can reach all three functions with neither present.

Developed in https://github.com/WordPress/wordpress-develop/pull/11851.
Follow-up to r48141, r55447, r57559, r57565.

Props deepakrohilla, westonruter, sabernhardt, wildworks, audrasjb.
See #64898.
Fixes #65259.

Note: See TracTickets for help on using tickets.