[wp-trac] [WordPress Trac] #39130: Docblock improvements for 4.8

[WordPress Trac]

#39130: Docblock improvements for 4.8
-------------------------------+-------------------
 Reporter:  johnbillion        |       Owner:
     Type:  task (blessed)     |      Status:  new
 Priority:  normal             |   Milestone:  4.8
Component:  General            |     Version:
 Severity:  normal             |  Resolution:
 Keywords:  ongoing has-patch  |     Focuses:  docs
-------------------------------+-------------------

Comment (by keesiemeijer):

 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
 [https://core.trac.wordpress.org/attachment/ticket/39130/39130.12.patch
 this patch].

 The actions in `/wp-admin/admin.php` are deprecated but should still be
 documented because of [https://github.com/WordPress/phpdoc-
 parser/issues/185 this issue] with the parser.

 In the [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php/ PHP Documentation Standards] handbook we
 should make it more clear that DocBlocks start with a double asterisk
 (`/**`) and should '''only be used''' for
 [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php/#what-should-be-documented these elements].
 For all other inline documentation
 [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php/#5-2-multi-line-comments multi-line] or
 [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php/#5-1-single-line-comments single-line]
 comments should be used. This is
 [https://core.trac.wordpress.org/browser/tags/4.7/src/wp-
 includes/theme.php#L800 an example of wrong DocBlock usage] that the
 parser picks up as a DocBlock and could potentially assign to a hook.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/39130#comment:6>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform