Standardize core file headers

[DrewAPicture]

Every file in WordPress should have file headers that follow the recommendations ​set out in the inline documentation standards.

This ticket will track my progress of overhauling core php file headers.

[DrewAPicture]

In 33869:

Docs: Improve the file header for class-wp-widget.php to describe what the file contains.

Also rewrites the class DocBlock summary for WP_Widget to better describe the purpose of the class.

See #33413. See #33701.

[DrewAPicture]

In 33870:

Docs: Clarify the file header summary for class-wp-widget-factory.php, introduced in [33746].

See #33413. See #33701.

[DrewAPicture]

In 33871:

Docs: Clarify the file header summary for widget-functions.php, introduced in [33746].

See #33413. See #33701.

[DrewAPicture]

In 33872:

Docs: Clarify the file header summary for wp-includes/widgets.php, the top-level file for the core Widgets API.

Also fixes some minor grammar issues in the file description.

See #33413. See #33701.

[DrewAPicture]

In 33873:

Docs: Add a missing file header to wp-includes/class-wp-http-cookie.php, introduced in [33748].

Also clarifies the summary in the class DocBlock for WP_Http_Cookie.

See #33413. See #33701.

[DrewAPicture]

In 33874:

Docs: Add a missing file header for wp-includes/class-wp-http-curl.php, introduced in [33748].

Also clarifies the class DocBlock summary for WP_Http_Curl to better describe its purpose.

See #33413. See #33701.

[DrewAPicture]

In 33875:

Docs: Add a missing file header for wp-includes/class-wp-http-encoding.php, introduced in [33748].

Also clarifies the class DocBlock summary for WP_Http_Encoding.

See #33413. See #33701.

[DrewAPicture]

In 33876:

Docs: Add a missing file header to wp-includes/class-wp-http-proxy.php, introduced in [33748].

Also clarifies the class DocBlock summary for WP_HTTP_Proxy to better describe its purpose.

See #33413. See #33701.

[DrewAPicture]

In 33878:

Docs: Add a missing file header to wp-includes/class-wp-http-streams.php, introduced in [33748].

Also clarifies the class DocBlock summary for WP_Http_Streams to better describe its purpose.

See #33413. See #33701.

[DrewAPicture]

In 33879:

Docs: Clarify the file header summary for wp-includes/http-functions.php, introduced in [33748].

Also removes now-moot extra information from the file header description.

See #33413. See #33701.

[DrewAPicture]

In 33880:

Docs: Add a missing file header for wp-includes/class-http.php.

Also clarifies the class DocBlock summary for WP_Http to more clearly describe its purpose.

See #33413. See #33701.

[DrewAPicture]

In 33881:

Docs: Clarify the file header summary for wp-includes/http.php, the top-level file for the HTTP Request API.

See #33413. See #33701.

[DrewAPicture]

In 33895:

Docs: Add a missing file header for wp-includes/class-wp-user-query.php, introduced in [33749].

Also clarifies the class DocBlock summary for WP_User_Query to better describe its purpose.

See #33413. See #33701.

[DrewAPicture]

In 33896:

Docs: Clarify the file header summary for wp-includes/user-functions.php, introduced in [33749].

See #33413. See #33701.

[DrewAPicture]

In 33897:

Docs: Clarify the file header summary for wp-includes/user.php, the top-level file for the core Users API.

Also adds inline DocBlocks for the require_once() calls that now bring in core users functionality and the WP_User_Query class, as of [33749].

See #33413. See #33701.

[DrewAPicture]

In 33898:

Docs: Add a missing file header for wp-includes/class-wp-comment-query.php, introduced in [33750].

Also clarifies the class DocBlock summary and tags for WP_Comment_Query.

See #33413. See #33701.

[DrewAPicture]

In 33899:

Docs: Clarify the file header summary for wp-includes/comment-functions.php, introduced in [33750].

See #33413. See #33701.

[DrewAPicture]

In 33900:

Docs: Clarify the file header summary for wp-includes/comment.php, the top-level file for the core Comments API.

Also adds inline DocBlock for the require_once() calls that now bring in the WP_Comment and WP_Comment_Query classes, as well as core comments functionality.

See #33413. See #33701.

[DrewAPicture]

In 33901:

Docs: Clarify the file header summary for wp-includes/rewrite-constants.php, introduced in [33751].

See #33413. See #33701.

[GaryJ]

I'd like to see this consistency applied to the empty index.php files found inside wp-content, plugins, and themes too. Currently there is just the following for each:

<?php
// Silence is golden.

It could be made a little less cryptic for those viewing the files, and adhering to code standards with something like:

<?php
/** 
 * Intentionally empty file
 *
 * This file exists to stop directory listings on poorly configured servers.
 */

The Summary could be adapted for each index.php to include the reference to which directory it is in, to avoid duplicate Summaries. The @package and other tags may be added if this has any value for wp-parser.

[DrewAPicture]

In 34392:

Docs: The Widget API is singular.

See #33701.

[DrewAPicture]

In 34393:

Docs: The User API is singular.

See #33701.

[DrewAPicture]

In 34394:

Docs: Add a file header to wp-includes/class-wp-roles.php, introduced in [33752].

Also adjusts the class DocBlock for WP_Roles.

See #33413. See #33701.

[DrewAPicture]

In 34395:

Docs: Add a file header to wp-includes/class-wp-role.php, introduced in [33752].

Also adjusts the class DocBlock for WP_Role.

See #33413. See #33701.

[DrewAPicture]

In 34396:

Docs: Clarify the file header summary for wp-includes/capabilities-functions.php, introduced in [33752].

See #33413. See #33701.

[DrewAPicture]

In 34397:

Docs: The User API is singular.

See #33701.

[DrewAPicture]

In 34398:

Docs: Clarify the file header summary for wp-includes/capabilities.php, which was broken up into multiple files in [33752].

Also adds inline DocBlocks for files now brought in via require_once() from this file.

See #33413. See #33701.

[DrewAPicture]

In 34399:

Docs: Add a file header to wp-includes/class-wp-post.php, introduced in [33759].

Also clarifies the class DocBlock for WP_Post.

See #33413. See #33701.

[DrewAPicture]

In 34400:

Docs: Clarify the file header summary for wp-includes/post-functions.php, introduced in [33759].

See #33413. See #33701.

[DrewAPicture]

In 34401:

Docs: Clarify the file header summary for wp-includes/post.php, the top-level file for the Post API.

See #33413. See #33701.

[DrewAPicture]

In 34402:

Docs: Add a file header to wp-includes/class-wp-tax-query.php, introduced in [33760].

Also clarifies the class DocBlock summary and description for WP_Tax_Query.

See #33413. See #33701.

[DrewAPicture]

In 34403:

Docs: Clarify the file header summary for wp-includes/taxonomy-functions.php, introduced in [33760].

See #33413. See #33701.

[DrewAPicture]

In 34404:

Docs: Clarify the file header summary for wp-includes/taxonomy.php, the top-level file for the core Taxonomy API.

See #33413. See #33701.

[DrewAPicture]

In 34405:

Docs: Add a file header to wp-includes/class-wp-meta-query.php, introduced in [33761].

Also clarifies the class DocBlock summary for WP_Meta_Query.

See #33413. See #33701.

[DrewAPicture]

In 34406:

Docs: Clarify the file header summary for wp-includes/meta-functions.php, introduced in [33761].

See #33413. See #33701.

[DrewAPicture]

In 34407:

Docs: Clarify the file header summary for wp-includes/meta.php, the top-level file for the core Meta API.

Also adds inline DocBlocks for files broken out in #33413 and now brought in via require_once().

See #33413. See #33701.

[DrewAPicture]

In 34408:

Docs: Clarify the file header summary for wp-includes/default-widgets.php, the top-level file for bringing in the core widget classes.

Also adds inline DocBlocks for the widget classes now brought in via require_once() as of [33843].

See #33413. See #33701.

[DrewAPicture]

In 34409:

Docs: The Comment API is singular.

See #33701.

[DrewAPicture]

In 34410:

Docs: The Comment API is singular.

See #33701.

[DrewAPicture]

In 34411:

Docs: The Comments subpackage is plural.

See #33701.

[DrewAPicture]

In 34412:

Docs: The Users subpackage is plural.

See #33701.

[DrewAPicture]

In 34413:

Docs: The Widgets subpackage is plural.

See #33701.

[DrewAPicture]

In 34414:

Docs: Clarify the file header summary for wp-includes/class-walker-page.php, introduced in [34109].

Also clarifies the class DocBlock summary for Walker_Page.

See #33413. See #33701.

[DrewAPicture]

In 34415:

Docs: Clarify the file header subpackage for wp-includes/class-walker-page-dropdown.php, introduced in [34109].

Also clarifies the class DocBlock summary and tags for Walker_PageDropdown.

See #33413. See #33701.

[DrewAPicture]

In 34416:

Docs: Clarify the file header summary for wp-includes/class-walker-category.php, introduced in [34110].

Also clarifies the class DocBlock and tags for Walker_Category.

See #33413. See #33701.

[DrewAPicture]

In 34417:

Docs: Clarify the file header for wp-includes/class-walker-category-dropdown.php, introduced in [34110].

Also clarifies the class DocBlock and tags for Walker_CategoryDropdown.

See #33413. See #33701.

[DrewAPicture]

In 34418:

Docs: Clarify the file header for wp-includes/category.php.

See #33413. See #33701.

[DrewAPicture]

In 34419:

Docs: Clarify the file header summary and subpackage for wp-includes/category-functions.php, introduced in [34110].

See #33413. See #33701.

[DrewAPicture]

In 34420:

Docs: Clarify the file header summary and version for wp-includes/category-template.php.

See #33413. See #33701.

[DrewAPicture]

In 34421:

Docs: Add a file header to wp-admin/includes/nav-menus.php.

See [34168]. See #33701.

[DrewAPicture]

In 34423:

Docs: Clarify the file header summary for wp-admin/includes/class-wp-post-comments-list-table.php, introduced in [34223].

Also clarifies the class DocBlock summary and tags for WP_Post_Comments_List_Table.

See #33413. See #33701.

[DrewAPicture]

In 34425:

Docs: Clarify the file header summary for wp-admin/includes/class-walker-category-checklist.php, introduced in [34241].

Also clarifies the class DocBlock summary for Walker_Category_Checklist.

See #33413. See #33701.

[DrewAPicture]

In 34426:

Docs: Clarify the file header summary for wp-admin/includes/class-wp-internal-pointers.php, introduced in [34241].

Also adds a missing class DocBlock to WP_Internal_Pointers. See [19388].

See #33413. See #33701.

[DrewAPicture]

In 34427:

Docs: Clarify the file header summary for wp-admin/includes/template-functions.php, introduced in [34241].

See #33413. See #33701.

[DrewAPicture]

In 34428:

Docs: Clarify the file header summary for wp-includes/widgets/class-wp-nav-menu-widget.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Nav_Menu_Widget.

See #33413. See #33701.

[DrewAPicture]

In 34429:

Docs: Add a missing file header to wp-includes/widgets/class-wp-widget-archives.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Archives.

See #33413. See #33701.

[DrewAPicture]

In 34430:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-calendar.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Calendar.

See #33413. See #33701.

[DrewAPicture]

In 34432:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-links.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Links.

See #33413. See #33701.

[DrewAPicture]

In 34433:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-meta.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Meta.

See #33413. See #33701.

[DrewAPicture]

In 34434:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-pages.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Pages.

See #33413. See #33701.

[DrewAPicture]

In 34435:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-recent-comments.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Recent_Comments.

See #33413. See #33701.

[DrewAPicture]

In 34436:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-recent-posts.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Recent_Posts.

See #33413. See #33701.

[DrewAPicture]

In 34437:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-rss.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_RSS.

See #33413. See #33701.

[DrewAPicture]

In 34438:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-search.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Search.

See #33413. See #33701.

[DrewAPicture]

In 34439:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-tag-cloud.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Tag_Cloud.

See #33413. See #33701.

[DrewAPicture]

In 34440:

Docs: Add a file header to wp-includes/widgets/class-wp-widget-text.php, introduced in [33746].

Also clarifies the class DocBlock summary and tags for WP_Widget_Text.

See #33413. See #33701.

[DrewAPicture]

In 34441:

Docs: Actually, the subpackage for Walker_Page should be Template.

See #33701.

[DrewAPicture]

In 34498:

Docs: Clarify the file header for wp-admin/includes/class-wp-upgrader.php.

See #33701.

[DrewAPicture]

In 35166:

Docs: Add a version and standardize the file header summary for wp-admin/includes/admin.php.

See #33701.

[DrewAPicture]

In 35167:

Docs: wp-admin/includes/admin-filters.php is part of the Administration subpackage, update the summary.

See #33701.

[DrewAPicture]

In 35168:

Docs: Standardize file header summary for wp-admin/includes/ajax-actions.php.

See #33701.

[ci skip]

[DrewAPicture]

In 35202:

Docs: Walker_Nav_Menu_Checklist and Walker_Nav_Menu_Edit are part of the Navigation Menu API, but intended for use in the scope of administration.

See #33701.

[DrewAPicture]

In 35221:

Docs: Standardize the file header summary for wp-admin/includes/file.php.

Also adds an @since version and corrects the @subpackage value.

See #33701.

[DrewAPicture]

In 35237:

Docs: Add a missing file header for wp-admin/includes/class-wp-list-table.php.

See #33701.

[DrewAPicture]

In 35241:

Docs: Add missing file headers to the list table classes and adjust class DocBlocks accordingly.

See #33701.

[DrewAPicture]

In 35262:

Docs: Add a version to the file header for wp-admin/includes/comment.php.

See #33701.

[DrewAPicture]

In 35271:

Docs: Add a missing file header for wp-admin/includes/class-wp-site-icon.php.

See #33701.

[DrewAPicture]

In 35359:

Docs: Add a proper file header to wp-admin/includes/continents-cities.php.

See #33701.

[DrewAPicture]

In 35387:

Docs: Add a version to the file header for wp-admin/includes/revision.php.

See #33701.

[DrewAPicture]

In 35403:

Docs: Add a @subpackage tag to the file header for wp-admin/includes/ms-admin-filters.php.

See #33701.

[DrewAPicture]

In 35407:

Docs: Standardize the file header for wp-admin/includes/ms-deprecated.php.

See #33701.

[DrewAPicture]

In 35558:

Docs: Add a missing version to the file header for wp-admin/users.php.

See #33701.

[DrewAPicture]

In 36497:

Docs: Add a missing version to the file header for wp-admin/term.php, introduced in [36308].

See #34988. See #33701.

[DrewAPicture]

In 36498:

Docs: Revert unintended changes in wp-includes/post.php, mistakenly included in [36497].

See #34988. See #33701.

[DrewAPicture]

Closing in favor of new tickets for individual issues.