Make WordPress Core

Opened 4 weeks ago

Last modified 4 days ago

#64224 new task (blessed)

Docblock improvements for 7.0

Reported by: desrosj's profile desrosj Owned by:
Milestone: 7.0 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: coding-standards Cc:

Description

Previously:

Change History (23)

#1 @SergeyBiryukov
4 weeks ago

  • Summary changed from Dockblock improvements for 7.0 to Docblock improvements for 7.0

#2 @westonruter
3 weeks ago

In 61270:

Docs: Add missing descriptions and fix types for some @return tags.

Props huzaifaalmesbah, sabernhardt, westonruter.
See #64224.
Fixes #64262.

#3 @SergeyBiryukov
3 weeks ago

In 61275:

Docs: Improve description for wp_insert_post().

Follow-up to [6379], [8669].

Props rutujaparamane2004.
See #64224.

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


3 weeks ago
#4

  • Keywords has-patch added

@SergeyBiryukov commented on PR #9286:


3 weeks ago
#5

Thanks for the PR! Merged in r61275.

#6 @westonruter
3 weeks ago

In 61278:

Docs: Update meta box action documentation to more accurately reflect the possible object types.

In addition to a meta box being able to be added for a post, it can also be added for a comment or a link, or even nothing at all when on the Dashboard.

Props opr18, nikunj8866, soyebsalar01, westonruter.
See #64224.
Fixes #64251.

#7 @westonruter
2 weeks ago

In 61299:

Docs: Update various class @var tags to indicate nullability.

This updates various @var tags on class properties to correctly indicate that the props may be null or unset:

  • WP_Dependencies::$all_queued_deps is nullable by both ::enqueue() and ::dequeue. Also, the types of the keys and values are specified.
  • WP_Duotone::$global_styles_presets and ::$global_styles_block_names start off unset and are only initialized by static classes.
  • WP_Query::init() and WP_Rewrite::init() are public methods that unset()s many class props.
  • WP_Theme::cache_delete() sets many props to null.

Developed in https://github.com/WordPress/wordpress-develop/pull/8953

Props justlevine, westonruter.
See #64238, #64224.

#8 @westonruter
2 weeks ago

In 61300:

Docs: Improve docblocks and types for WP_Screen properties.

  • Correctly hint that WP_Screen::$_show_screen_options is null before being instantiated.
  • Correctly hint that ::get_option(), get_help_tab() and get_screen_reader_text() can return null.
  • Ensure $this->columns is an int, by casting $this->get_option( 'layout_columns', 'default' ) from its numeric string.

Developed in https://github.com/WordPress/wordpress-develop/pull/8860

Props justlevine, peterwilsoncc, westonruter.
See #64238, #64224.

#9 @westonruter
2 weeks ago

In 61302:

Bundled Themes: Add missing @return tags and descriptions.

Developed in https://github.com/WordPress/wordpress-develop/pull/10533

Props huzaifaalmesbah, sabernhardt, palak678, westonruter.
See #64224.
Fixes #64277.

#10 @westonruter
2 weeks ago

In 61309:

Twenty Eleven: Improve PHP docblocks with corrected descriptions, missing/corrected tags, and specific types.

Developed in https://github.com/WordPress/wordpress-develop/pull/10482

Props huzaifaalmesbah, dhruvang21, juanfra, sabernhardt, noruzzaman, ravichudasama01, westonruter.
See #64224.
Fixes #64211.

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


13 days ago
#11

### Description
This PR adds missing variable names to @param tags in Twenty Eleven, Twenty Ten, and Twenty Twenty themes.

### Changes
Twenty Eleven: category.php, functions.php
Twenty Ten: loop-attachment.php, author.php
Twenty Twenty: functions.php, inc/template-tags.php, template-parts/entry-header.php, template-parts/content-cover.php

### Testing Instructions

  1. Navigate to the affected files.
  2. Verify that the docblocks for the mentioned filters now include the variable names in the @param tags.
  3. Ensure no PHP errors or warnings are generated.

#12 @SergeyBiryukov
12 days ago

In 61314:

Twenty Ten: Add missing variable names to some @param tags.

Follow-up to [25627].

Props huzaifaalmesbah.
See #64224.

#13 @SergeyBiryukov
12 days ago

In 61315:

Twenty Eleven: Add missing variable names to some @param tags.

Follow-up to [25625].

Props huzaifaalmesbah.
See #64224.

#14 @SergeyBiryukov
11 days ago

In 61317:

Twenty Twenty: Add missing variable names to some @param tags.

Follow-up to [46271], [46357], [51322].

Props huzaifaalmesbah.
See #64224.

#15 @westonruter
11 days ago

In 61319:

Twenty Twenty: Fix typo and improve param description for twentytwenty_read_more_tag().

Follow-up to [61302].

Props sabernhardt.
See #64277, #64224.

#16 @westonruter
10 days ago

In 61322:

Docs: Improve accuracy of wp_enqueue_classic_theme_styles() description.

Developed in https://github.com/WordPress/wordpress-develop/pull/10565

Follow-up to [59980], [54687], [54358].

Props manhphucofficial, wildworks, sabernhardt, iflairwebtechnologies, westonruter.
See #61892, #64224.
Fixes #64317.

@noruzzaman commented on PR #10562:


10 days ago
#17

I have followed the testing instructions for Twenty Eleven, Twenty Ten, and Twenty Twenty.
The updated docblocks now include the missing parameter names ($html, $width, $height, $size, $elements, $post_types, $show_categories), and I’m not seeing any PHP warnings or notices.

This looks good to me and improves the clarity of the bundled theme docs.

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


10 days ago
#18

## Description
Improves inline documentation for WP_Comments_List_Table in wp-admin/includes/class-wp-comments-list-table.php to align with WordPress coding standards.

## Changes

  • Added missing summary descriptions.
  • Improved specificity of @return and @param tags.

## Testing Instructions

  1. Inspect src/wp-admin/includes/class-wp-comments-list-table.php.
  2. Verify docblocks follow standards.

@SergeyBiryukov commented on PR #10562:


10 days ago
#19

Thanks for the PR! Merged in r61314, r61315, and r61317.

@noruzzaman commented on PR #10569:


9 days ago
#20

Thanks for the update @huzaifaalmesbah! I have gone through the changes, and everything looks cleaner and much easier to follow now. The added descriptions and improved @return / @param details definitely make the docblocks more useful.
Nice improvement overall.

@huzaifaalmesbah commented on PR #10569:


9 days ago
#21

@westonruter Thank you for your review and suggestions. I’ve applied the changes you recommended.

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


9 days ago
#22

## Description
This PR improves inline documentation in wp-admin files by adding missing parameter descriptions to function docblocks.

## Changes

  • ✅ Added proper @param descriptions for functions missing them
  • ✅ Added complete docblock for wp_load_press_this() function
  • ✅ Enhanced function summary for wp_nav_menu_max_depth()
  • ✅ All changes follow WordPress PHP Documentation Standards

## Files Modified

  • wp-admin/install.php
  • wp-admin/nav-menus.php
  • wp-admin/update-core.php
  • wp-admin/includes/ajax-actions.php
  • wp-admin/includes/class-wp-importer.php

## Testing

  • [x] No functional changes, documentation only
  • [x] All parameter descriptions are accurate and follow WP standards

#23 @SergeyBiryukov
4 days ago

In 61356:

Docs: Add missing parameter descriptions in wp-admin/install.php.

Follow-up to [32654].

Props rejaulalomkhan.
See #64224.

Note: See TracTickets for help on using tickets.