Make WordPress Core

#57840 closed task (blessed) (fixed)

Docblock improvements for 6.3

Reported by: hellofromtonya's profile hellofromTonya Owned by:
Milestone: 6.3 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch dev-reviewed commit
Focuses: docs, coding-standards Cc:

Description

Previously:

Attachments (3)

57840.diff (5.5 KB) - added by Presskopp 12 months ago.
went through them all again and this is the patch so far
57840-twentyseventeen-docs.diff (1.3 KB) - added by sabernhardt 11 months ago.
Twenty Seventeen: correcting a typo and removing a word that never belongs in documentation (props mukesh27)
wp_rest_attachments_controller-upload_from_data.diff (824 bytes) - added by costdev 11 months ago.
The $data parameter in WP_REST_Attachments_Controller::upload_from_data() is passed and treated only as string, not array.

Download all attachments as: .zip

Change History (93)

#1 @SergeyBiryukov
15 months ago

In 55539:

Docs: Improve some DocBlock formatting in wp-includes/class-wp-xmlrpc-server.php.

Includes clarifying the list of fields passed to the xmlrpc_default_*_fields filters by default.

Follow-up to [16046], [17647], [27730], [32550], [37492], [55316].

See #57840.

This ticket was mentioned in PR #4347 on WordPress/wordpress-develop by SweetSue.


13 months ago
#2

  • Keywords has-patch added

#3 @pouicpouic
13 months ago

Hi, this is my first contribution, at WordCamp Paris April 2023.

#4 @audrasjb
13 months ago

Hi there, just noting that we are at WordCamp Paris contributor day right now, and we're going to use small Docblock changes to onboard people on the contribution process to Core :)

Last edited 13 months ago by audrasjb (previous) (diff)

#6 @laurentmagnin
13 months ago

Hi, this is my first contribution, at WordCamp Paris April 2023.

#7 @audrasjb
13 months ago

In 55663:

Docs: Use third-person singular verbs for WP_Importer related function descriptions, as per docblocks standards.

Props pouicpouic.
See #57840.

#8 @audrasjb
13 months ago

In 55664:

Docs: Use third-person singular verbs for WP_Importer related function descriptions, as per docblocks standards.

Props pouicpouic.
See #57840.

#12 @jbcouton
13 months ago

Hi, this is my first core contribution, at WordCamp Paris April 2023.

#13 @audrasjb
13 months ago

In 55681:

Docs: Use third-person singular verbs in various function descriptions, as per docblocks standards.

Props laurentmagnin, pouicpouic, jbcouton, audrasjb.
See #57840.

#18 @johnbillion
13 months ago

In 55693:

Docs: Correct and improve various documented types for properties, functions, and hooks.

See #57840

#19 @johnbillion
13 months ago

In 55694:

Docs: All sorts of improvements and corrections to function and hook docs.

See #57840

#20 @audrasjb
13 months ago

In 55705:

Docs: Various improvements in Bookmark Administration API function descriptions, as per docblocks standards.

Follow-up to [55704].

See #57840.

#21 @johnbillion
13 months ago

In 55711:

Docs: Corrections and improvements to docblocks for global styles, global settings, theme.json parsing, and shortcodes.

See #57840

This ticket was mentioned in PR #4419 on WordPress/wordpress-develop by @johnbillion.


13 months ago
#22

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

There's many helpful code examples in the docs for the WP_HTML_Tag_Processor class but they're all indented by four unnecessary spaces. They use the <code>`php</code> wrapper which makes the indentation appear in the code blocks on the developer reference site. This fixes that by removing the extraneous indentation.

There's also an additional fix for the note about the U+FFFD character.

Example URLs that display the unnecessary indentation:

#23 @johnbillion
13 months ago

In 55712:

Docs: Miscellaneous formatting corrections to inline docs and whitespace.

See #57840

#24 @johnbillion
13 months ago

In 55714:

Filesystem API: Correct and improve the return type documentation for the dirlist() method in WP_Filesystem_Base and its extending classes.

Props mat-lipe, szepeviktor, costdev, audrasjb, johnbillion

Fixes #58229
See #57840

#26 @johnbillion
13 months ago

In 55718:

Docs: Improve formatting of markup in the docs for WP_HTML_Tag_Processor.

Code blocks wrapped inside backtacks don't need to be indented.

See #57840

#28 @johnbillion
13 months ago

In 55719:

Docs: Correct and improve inline docs relating to the style engine.

See #57840

@dmsnell commented on PR #4419:


13 months ago
#30

Thanks @johnbillion - I was under the impression the indentation was required, but I've double-checked after this change and the code still renders as code at least in PHPStorm and VSCode.

@dmsnell commented on PR #4419:


13 months ago
#31

@johnbillion what was wrong with the U+FFFD note?
looks right to me in the linked documentation, which I think is still reflecting the code before this change

https://i0.wp.com/user-images.githubusercontent.com/5431237/236154537-9fee734b-465b-4176-8fe3-f503883329ef.png

@johnbillion commented on PR #4419:


13 months ago
#32

I was under the impression the indentation was required

Yeah you just need either the backticks or the indentation but not both 😄

what was wrong with the U+FFFD note?

It was just to remove the unprintable character from the source code 👍

looks right to me in the linked documentation

Yeah the docs on the developer reference site only get regenerated from the source when each new version of WordPress is released

@dmsnell commented on PR #4419:


13 months ago
#33

but not both

ahaa

It was just to remove the unprintable character from the source code 👍

that character _is_ printable though, and it printed

maybe it's confusing because _that character_ is the character used _when the string has invalid characters in it_?

I think maybe it was a mistake to remove. we added that originally to show what it is, thinking people would more readily recognize � than U+FFFD

@johnbillion commented on PR #4419:


13 months ago
#34

Ohhhh _that_ is the actual unicode character displayed as a replacement when a character is unprintable? I see.

@dmsnell commented on PR #4419:


13 months ago
#35

@johnbillion do you have any thoughts about me adding it back in? maybe surround it in quotes this time to try and make it more obvious that it's the actual character?

sorry this wasn't caught in review. I would have noted it, but the PR was created and merged before I was still asleep

#36 @audrasjb
13 months ago

In 55723:

HTML API: Restore mistakenly-removed content in documentation.

In [55718] the Unicode replacement character was mistakenly removed. The purpose of including the character was to communicate what it looks like and why the Tag Processor won't insert it into the document.

This changeset brings the character back and adds a small clue to fix the confusion that may lead to its removal.

Follow-up to [55718].

Props dmsnell.
Fixes #58256
See #57840.

#37 @SergeyBiryukov
13 months ago

In 55725:

Docs: Remove @return void from various DocBlocks.

Per the documentation standards, it should not be used outside of the default bundled themes.

Follow-up to [52049], [52051], [53331], [54156], [54214], [55203], [55719].

See #57840.

#38 @johnbillion
13 months ago

In 55732:

Docs: A host of corrections and improvements to inline documentation.

See #57840

#39 @SergeyBiryukov
13 months ago

In 55733:

Docs: Improve Style Engine file and class headers per the documentation standards.

Follow-up to [54156], [55719].

See #57840.

#40 @SergeyBiryukov
13 months ago

In 55734:

Docs: Improve HTML API file and class headers per the documentation standards.

Follow-up to [55203], [55304], [55718], [55724], [55727].

See #57840.

#41 @johnbillion
13 months ago

In 55753:

Docs: Various corrections and improvements to inline docs and docblocks.

See #57840

#42 @SergeyBiryukov
12 months ago

In 55819:

Docs: Improve Style Engine DocBlocks per the documentation standards.

Follow-up to [54156], [55719], [55733].

See #57840.

#43 @SergeyBiryukov
12 months ago

In 55820:

Docs: Correct default value for the $optimize option in Style Engine.

The default value is set to true in WP_Style_Engine_Processor::get_css(), but was previously documented as false in various DocBlocks.

Follow-up to [54156], [55719], [55733], [55819].

See #57840.

#44 follow-up: @dmsnell
12 months ago

@SergeyBiryukov do you mind backporting the changes you made to the HTML API to Gutenberg? every update in Core needs to be followed by such a change so the two sides don't get out of sync. I'm happy to review/approve the "blessed" PR over there for you.

#45 @SergeyBiryukov
12 months ago

In 55824:

Docs: Fix a few more typos in inline comments.

Follow-up to [9117], [11005], [12097], [18632], [26192], [55823].

Props Presskopp.
See #58334, #57840.

#46 in reply to: ↑ 44 ; follow-up: @SergeyBiryukov
12 months ago

Replying to dmsnell:

do you mind backporting the changes you made to the HTML API to Gutenberg? every update in Core needs to be followed by such a change so the two sides don't get out of sync.

I was not aware of that, thanks! Sure, will create a PR :)

#47 @Presskopp
12 months ago

More 'a' => 'an' candidates:

\src\wp-admin\includes\class-bulk-upgrader-skin.php

Line 82: Nothing, This will be displayed within a iframe.

\src\wp-admin\includes\class-pclzip.php

Line 637: read_error : the file was not extracted because there was a error

\src\wp-admin\includes\file.php

Line 1380: Check for a edge-case affecting PHP Maths abilities.

\src\wp-includes\class-wp-http-cookie.php

Line 139: Handle the cookie ending in ; which results in a empty final pair.

\src\wp-includes\class-wp-http.php

Line 1083: * '4' or '6' to represent a IPv4 and IPv6 address respectively.

\src\wp-includes\class-wp-oembed.php

Line 517: * Connects to a oEmbed provider and returns the result.

\src\wp-includes\media-template.php

Line 11: * Outputs the markup for a audio tag to be used in an Underscore template

\src\wp-includes\media.php

Line 4814: * Checks the HTML content for a audio, video, object, embed, or iframe tags.

\src\wp-includes\option.php

Line 1373: * Removes a option by name for the current network.

\src\wp-includes\Requests\src\IdnaEncoder.php

Line 29: * Maximum length of a IDNA URL in ASCII.

\src\wp-includes\customize\class-wp-customize-nav-menu-item-setting.php

Line 231: Note that a ID of less than one indicates a nav_menu not yet inserted.

Last edited 12 months ago by Presskopp (previous) (diff)

@Presskopp
12 months ago

went through them all again and this is the patch so far

#48 @SergeyBiryukov
12 months ago

In 55827:

Docs: Fix a few more typos in DocBlocks and inline comments.

Follow-up to [6779], [10565], [12023], [25224], [27533], [32806], [34777], [45262], [46594], [55823], [55824].

Props Presskopp.
See #57840.

#49 @SergeyBiryukov
12 months ago

In 55843:

Docs: Fix a few more typos in DocBlocks.

Follow-up to [39493], [41726], [55823], [55824], [55827].

See #57840.

#50 in reply to: ↑ 46 @dmsnell
12 months ago

Replying to SergeyBiryukov:

Replying to dmsnell:

do you mind backporting the changes you made to the HTML API to Gutenberg? every update in Core needs to be followed by such a change so the two sides don't get out of sync.

I was not aware of that, thanks! Sure, will create a PR :)

Thanks @SergeyBiryukov - you can use #48812 as an example.

This workflow is the result of developing the work in Core first and keeping Gutenberg in sync, since that seems to be how everyone prefers it, and since it's easier getting these updates into the plugin (we just need to make sure we do that).

Feel free to add me as a reviewer.

#51 @audrasjb
12 months ago

#58340 was marked as a duplicate.

#52 @johnbillion
12 months ago

In 55870:

Docs: Miscellaneous corrections and improvements to docblocks.

See #57840

#53 @audrasjb
12 months ago

In 55882:

Docs: Various docblock improvements in Custom Header Image related functions, as per docblocks standards.

See #57840.

#56 @costdev
12 months ago

@audrasjb PR 4551 and PR 4552 target some docblocks that are missing third-person singular verbs.

#57 @audrasjb
12 months ago

Thanks! 👀

#58 @audrasjb
12 months ago

In 55884:

Docs: Fix a few more typos in Docblocks.

Follow-up to [6779], [10565], [12023], [25224], [27533], [32806], [34777], [45262], [46594], [55823], [55824], [55827].

Props nazmulhudadev, mukesh27.
Fixes #58338.
See #57840.

#59 @audrasjb
12 months ago

In 55887:

Docs: Improve various docblock in WP_Query class, as per docblock standards.

See #57840.

#60 @audrasjb
12 months ago

In 55893:

Docs: Mark apply_filters() third parameter $args as optional.

The $args parameter of apply_filters() is optional. This changeset updates the related Docblock description accordingly so the parameter is not marked as
required on DevHub.

Props gaeldenysiak, audrasjb, gilles66.
Fixes #58481.
See #57840.

@audrasjb commented on PR #4551:


12 months ago
#61

Added a commit to resolve a conflict.

#62 @audrasjb
12 months ago

In 55911:

Docs: Use third-person singular verbs in various function descriptions, as per docblocks standards.

Props costdev, audrasjb.
See #57840.

@audrasjb commented on PR #4552:


12 months ago
#63

Thanks for the update!
Committed in https://core.trac.wordpress.org/changeset/55911

#64 @audrasjb
12 months ago

In 55916:

Docs: Use third-person singular verbs in various function descriptions, as per docblocks standards.

Follow-up to [55911].

Props costdev, audrasjb.
See #57840.

#65 @audrasjb
12 months ago

In 55917:

Docs: Use third-person singular verbs in various function descriptions, as per docblocks standards.

Follow-up to [55911], [55916].

Props costdev.
See #57840.

#66 @audrasjb
12 months ago

In 55918:

Docs: Use third-person singular verbs in various function descriptions, as per docblocks standards.

Follow-up to [55911], [55916], [55917].

Props costdev.
See #57840.

#68 @audrasjb
11 months ago

In 55952:

Docs: register_block_style() docblock improvement.

This changeset replaces style with style_handle in the description of $style_properties to better match WP_Block_Styles_Registry::register().

Follow-up to [46111], [48102].

Props bacoords, dilipbheda, audrasjb.
Fixes #58562.
See #57840.

#69 @audrasjb
11 months ago

In 55962:

Docs: Add missing param description to update_menu_item_cache in wp_get_nav_menu_items().

Because update_menu_item_cache parameter doesn't have any description in this function, the wp_get_nav_menu_items() documentation page on DevHub fallbacks
to get_post() params descriptions… which fallbacks to parse_query().

In parse_query(), the update_menu_item_cache param is set to false by default, so wp_get_nav_menu_items() ends up with a value of false by default,
which is wrong since wp_get_nav_menu_items() overrides this parameter to set it to true by default.

This changeset adds update_menu_item_cache parameter to wp_get_nav_menu_items() docblock, and indicates that it is set to true by default.

Follow-up to [53504].

Props audrasjb, matmoe.
Fixes #58468.
See #57840.

@sabernhardt
11 months ago

Twenty Seventeen: correcting a typo and removing a word that never belongs in documentation (props mukesh27)

#70 @audrasjb
11 months ago

In 56118:

Twenty Twenty-One: Improve various globals documentation, as per docblock standards.

This changeset adds globals documentation, and also a couple Docblock standards improvements.

Props upadalavipul, audrasjb.
Fixes #58684.
See #57840.

#71 @sabernhardt
11 months ago

I added more to my patch and moved it to its own ticket: #58695.

#72 @audrasjb
11 months ago

In 56121:

Twenty Seventeen: Various docblock fixes.

Props sabernhardt, audrasjb.
Fixes #58695.
See #57840.

#73 @audrasjb
11 months ago

In 56122:

Docs: Fix image_get_intermediate_size() docblock.

The description of returned values in array was incorrect for image_get_intermediate_size():

  • $file returns the filename of image, no path information
  • $path returns path relative to the uploads directory, not absolute

Props crstauf, sccr410.
Fixes #58686.
See #57840.

#74 @SergeyBiryukov
11 months ago

In 56144:

Docs: Document the return value of wp_check_php_version() using hash notation.

Follow-up to [42832].

See #57840.

#75 @audrasjb
11 months ago

In 56153:

Docs: Use third-person singular verbs in various function descriptions of load.php, as per docblocks standards.

See #57840.

#76 @johnbillion
11 months ago

In 56157:

Docs: Correct the formatting of various filter documentation.

See #57840

#77 @audrasjb
11 months ago

In 56165:

Docs: Update link to MovableType documentation.

Props mujuonly.
Fixes #58760.
See #57840.

@costdev
11 months ago

The $data parameter in WP_REST_Attachments_Controller::upload_from_data() is passed and treated only as string, not array.

#78 @audrasjb
11 months ago

In 56167:

Docs: Update link to MovableType docs (on Internet Archive).

Follow-up to [56165].

Props SergeyBiryukov.
Fixes #58760.
See #57840.

#79 @audrasjb
11 months ago

In 56168:

Docs: Docblock correction in WP_REST_Attachments_Controller::upload_from_data().

The $data parameter in WP_REST_Attachments_Controller::upload_from_data() is passed and treated only as string, not array.

Props costdev.
See #57840.

#80 @audrasjb
11 months ago

In 56204:

Docs: Fix incorrect type for $crop param is various WP_Image_Editor classes and methods.

This changeset updates the $crop docblock type in various WP_Image_Editor, WP_Image_Editor_GD and WP_Image_Editor_Imagick functions, to match the
type documented in image_resize_dimensions().

Props thunderdw.
Fixes #58271.
See #57840.

#81 @SergeyBiryukov
11 months ago

In 56231:

Docs: Clarify where the wp_get_development_mode() value is retrieved from.

Includes:

  • Adding a mention of the WP_DEVELOPMENT_MODE constant.
  • Minor DocBlock formatting adjustments.

Follow-up to [56042], [56223].

See #57487, #57840.

#82 @SergeyBiryukov
11 months ago

In 56232:

Docs: Use consistent wording for development mode.

Follow-up to [56042], [56223], [56231].

See #57487, #57840.

This ticket was mentioned in Slack in #core by mukeshpanchal27. View the logs.


10 months ago

#84 @audrasjb
10 months ago

In 56256:

Docs: Fix various incorrect @since mentions.

Props costdev, mukesh27.
Fixes #58834.
See #57840.

#85 @audrasjb
10 months ago

In 56257:

Docs: Various docblocks corrections.

See #57840.

#86 @audrasjb
10 months ago

In 56272:

Docs: Fix indentation issue in WP_REST_Global_Styles_Revisions_Controller class.

Follow-up to [56082].

See #57840, #58524.

#87 @audrasjb
10 months ago

If any committer is available, I formally need a second committer sign-off to backport the above patch 👆

#88 @joedolson
10 months ago

  • Keywords dev-reviewed commit added

Looks good!

#89 @joedolson
10 months ago

In 56280:

Docs: Fix indentation issue in WP_REST_Global_Styles_Revisions_Controller class.

Follow-up to [56082].
Reviewed by joedolson.
Merges [56272] to the 6.3 branch.
See #57840, #58524.

#90 @audrasjb
10 months ago

  • Resolution set to fixed
  • Status changed from new to closed

RC3 was just released. Let's close this one as fixed.
Thanks everyone!

Note: See TracTickets for help on using tickets.