Opened 4 months ago
Last modified 6 days ago
#53399 new task (blessed)
Docblock improvements for WP 5.9
Reported by: | desrosj | Owned by: | |
---|---|---|---|
Milestone: | 5.9 | Priority: | normal |
Severity: | normal | Version: | |
Component: | General | Keywords: | |
Focuses: | docs | Cc: |
Attachments (2)
Change History (42)
#15
follow-up:
↓ 16
@
3 months ago
@johnbillion Removing @global
tags for $wp_local_package
and $wp_locale
in setup_config_display_header()
doesn't seem correct, they are both used further in the function.
Should we perhaps declare them explicitly instead of accessing via the $GLOBALS
array?
#16
in reply to:
↑ 15
;
follow-up:
↓ 17
@
3 months ago
Replying to SergeyBiryukov:
they are both used further in the function
They actually fall outside of the function, which ends a few lines above. I didn't check but I suspect that's the original intention of those docs.
#17
in reply to:
↑ 16
@
3 months ago
Replying to johnbillion:
They actually fall outside of the function, which ends a few lines above.
Ah, yes, you're right. The docs were added in [32642], apparently due to a similar mistake that I made.
#27
follow-up:
↓ 31
@
2 months ago
53399.internal.diff converts two @internal
notes in wp-includes/ms-load.php
to @since
tags.
This would be more consistent with other similar @since
notes in core:
the_author_posts_link()
:@since 4.4.0 Converted into a wrapper for get_the_author_posts_link()
date_i18n()
:@since 5.3.0 Converted into a wrapper for wp_date().
language_attributes()
:@since 4.3.0 Converted into a wrapper for get_language_attributes().
WP_REST_Server::error_to_response()
@since 5.7.0 Converted to a wrapper of {@see rest_convert_error_to_response()}.
This would be a follow-up to [34099] and [38515]. However, I noticed that it reverts a part of [38201].
@johnbillion Do you have a preference here? Perhaps the notes above should be converted to @internal
instead?
#31
in reply to:
↑ 27
;
follow-up:
↓ 32
@
7 weeks ago
Replying to SergeyBiryukov:
Do you have a preference here? Perhaps the notes above should be converted to
@internal
instead?
@SergeyBiryukov To be honest I don't think these comments provide value to a developer. Whether or not a function internally wraps another one is of no consequence if it doesn't affect its external API. I'd be in favour of removing them.
#32
in reply to:
↑ 31
@
7 weeks ago
Replying to johnbillion:
To be honest I don't think these comments provide value to a developer. Whether or not a function internally wraps another one is of no consequence if it doesn't affect its external API. I'd be in favour of removing them.
I think this falls under the last point in @since Section (Changelogs):
If significant changes have been made to a function, hook, class, or method, additional
@since
tags, versions, and descriptions should be added to provide a changelog for that function.
“Significant changes” include but are not limited to:
- Adding new arguments or parameters
- Required arguments becoming optional
- Changing default/expected behaviors
- Functions or methods becoming wrappers for new APIs
Personally, I see some value in being able to tell if there is another function that can be used as a suitable replacement, and in which version the change was made.
In 51278: