Make WordPress Core

Opened 3 months ago

Last modified 5 days ago

#57840 new task (blessed)

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
Focuses: docs, coding-standards Cc:

Description

Previously:

Attachments (1)

57840.diff (5.5 KB) - added by Presskopp 11 days ago.
went through them all again and this is the patch so far

Download all attachments as: .zip

Change History (52)

#1 @SergeyBiryukov
3 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.


6 weeks ago
#2

  • Keywords has-patch added

#3 @pouicpouic
6 weeks ago

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

#4 @audrasjb
6 weeks 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 6 weeks ago by audrasjb (previous) (diff)

#6 @laurentmagnin
6 weeks ago

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

#7 @audrasjb
6 weeks 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
6 weeks 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
6 weeks ago

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

#13 @audrasjb
5 weeks 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
4 weeks ago

In 55693:

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

See #57840

#19 @johnbillion
4 weeks ago

In 55694:

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

See #57840

#20 @audrasjb
4 weeks ago

In 55705:

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

Follow-up to [55704].

See #57840.

#21 @johnbillion
4 weeks 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.


4 weeks 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
4 weeks ago

In 55712:

Docs: Miscellaneous formatting corrections to inline docs and whitespace.

See #57840

#24 @johnbillion
4 weeks 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
4 weeks 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
4 weeks ago

In 55719:

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

See #57840

@dmsnell commented on PR #4419:


4 weeks 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:


4 weeks 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:


4 weeks 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:


4 weeks 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:


4 weeks 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:


4 weeks 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
3 weeks 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
3 weeks 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
3 weeks ago

In 55732:

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

See #57840

#39 @SergeyBiryukov
3 weeks ago

In 55733:

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

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

See #57840.

#40 @SergeyBiryukov
3 weeks 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
2 weeks ago

In 55753:

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

See #57840

#42 @SergeyBiryukov
12 days ago

In 55819:

Docs: Improve Style Engine DocBlocks per the documentation standards.

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

See #57840.

#43 @SergeyBiryukov
12 days 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 days 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
11 days 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
11 days 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
11 days 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 11 days ago by Presskopp (previous) (diff)

@Presskopp
11 days ago

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

#48 @SergeyBiryukov
10 days 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
9 days 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
9 days 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
5 days ago

#58340 was marked as a duplicate.

Note: See TracTickets for help on using tickets.