WordPress.org

Make WordPress Core

Opened 9 months ago

Closed 3 months ago

#39130 closed task (blessed) (fixed)

Docblock improvements for 4.8

Reported by: johnbillion Owned by:
Milestone: 4.8 Priority: normal
Severity: normal Version:
Component: General Keywords: ongoing has-patch
Focuses: docs Cc:

Description

Follow-up to #37770.

Attachments (13)

39130.patch (888 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/functions.php
39130.2.patch (1.0 KB) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/general-template.php
39130.3.patch (974 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/kses.php
39130.4.patch (843 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/link-template.php
39130.5.patch (550 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/media-template.php
39130.6.patch (600 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/media.php
39130.7.patch (485 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/ms-functions.php
39130.8.patch (409 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/nav-menu.php
39130.9.patch (1.3 KB) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/pluggable.php
39130.10.patch (698 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/rest-api.php
39130.11.patch (469 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/taxonomy.php
39130.12.patch (468 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/theme.php
39130.13.patch (375 bytes) - added by keesiemeijer 8 months ago.
improvements for /wp-includes/vars.php

Download all attachments as: .zip

Change History (26)

#1 @johnbillion
9 months ago

In 39530:

Taxonomy: Correct the type for the first parameter of the the_category filter.

See #39130

@keesiemeijer
8 months ago

improvements for /wp-includes/functions.php

@keesiemeijer
8 months ago

improvements for /wp-includes/general-template.php

@keesiemeijer
8 months ago

improvements for /wp-includes/kses.php

@keesiemeijer
8 months ago

improvements for /wp-includes/link-template.php

@keesiemeijer
8 months ago

improvements for /wp-includes/media-template.php

@keesiemeijer
8 months ago

improvements for /wp-includes/media.php

@keesiemeijer
8 months ago

improvements for /wp-includes/ms-functions.php

@keesiemeijer
8 months ago

improvements for /wp-includes/nav-menu.php

@keesiemeijer
8 months ago

improvements for /wp-includes/pluggable.php

@keesiemeijer
8 months ago

improvements for /wp-includes/rest-api.php

@keesiemeijer
8 months ago

improvements for /wp-includes/taxonomy.php

@keesiemeijer
8 months ago

improvements for /wp-includes/theme.php

@keesiemeijer
8 months ago

improvements for /wp-includes/vars.php

#2 @johnbillion
8 months ago

  • Keywords has-patch added

#3 @keesiemeijer
8 months ago

Just to clarify some of the patches.

In 39130.5.patch the DocBlock is not found by the parser because it's a comment. This has the consequence that it's imported as a duplicate filter (without the parameters).
https://developer.wordpress.org/reference/hooks/image_size_names_choose-4/

In 39130.7.patch the @since parameter is only picked up by the parser if there's only one space before it. Now it's displayed in the description section instead of the change log section.
https://developer.wordpress.org/reference/functions/wp_update_network_counts/

#4 @johnbillion
8 months ago

In 39638:

Docs: Add and correct @since docs for a variety of functions and methods.

Props keesiemeijer, chris_dev
Fixes #39343, #39357, #39344
See #39130

#5 @johnbillion
8 months ago

In 39639:

Docs: Misc corrections and additions to inline documentation.

See #39130
Props keesiemeijer

#6 @keesiemeijer
8 months ago

These hooks should be documented:

  • load-page-new.php in /wp-admin/admin.php
  • load-page.php in /wp-admin/admin.php
  • load-categories.php in /wp-admin/admin.php
  • load-edit-link-categories.php in /wp-admin/admin.php
  • load-edit-tags.php in /wp-admin/admin.php
  • header_video_settings in /wp-includes/theme.php

For the header_video_settings filter there's this patch.

The actions in /wp-admin/admin.php are deprecated but should still be documented because of this issue with the parser.

In the PHP Documentation Standards handbook we should make it more clear that DocBlocks start with a double asterisk (/**) and should only be used for these elements. For all other inline documentation multi-line or single-line comments should be used. This is an example of wrong DocBlock usage that the parser picks up as a DocBlock and could potentially assign to a hook.

#7 @SergeyBiryukov
7 months ago

In 40043:

Docs: Clarify that get_the_category_list() and the_category() display links as an unordered list by default.

See #39130.

#8 @SergeyBiryukov
7 months ago

In 40046:

Docs: Use third-person singular verb for wp_get_custom_css filter description.

See #39130.

#9 @SergeyBiryukov
7 months ago

In 40047:

Docs: Use third-person singular verb for rest_avatar_sizes filter description.

See #39130.

#10 @DrewAPicture
5 months ago

In 40298:

Docs: Add a missing return description for get_post_taxonomies().

h/t deeptiboddapati.
See #39130.

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


3 months ago

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


3 months ago

#13 @obenland
3 months ago

  • Resolution set to fixed
  • Status changed from new to closed
Note: See TracTickets for help on using tickets.