WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#33701 closed task (blessed) (fixed)

Standardize core file headers

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: 4.5 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:

Description (last modified by 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.

Change History (89)

#1 @DrewAPicture
5 years ago

  • Description modified (diff)
  • Owner set to DrewAPicture
  • Status changed from new to accepted

#2 @DrewAPicture
5 years ago

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.

#3 @DrewAPicture
5 years ago

In 33870:

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

See #33413. See #33701.

#4 @DrewAPicture
5 years ago

In 33871:

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

See #33413. See #33701.

#5 @DrewAPicture
5 years ago

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.

#6 @DrewAPicture
5 years ago

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.

#7 @DrewAPicture
5 years ago

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.

#8 @DrewAPicture
5 years ago

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.

#9 @DrewAPicture
5 years ago

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.

#10 @DrewAPicture
5 years ago

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.

#11 @DrewAPicture
5 years ago

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.

#12 @DrewAPicture
5 years ago

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.

#13 @DrewAPicture
5 years ago

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.

#14 @DrewAPicture
5 years ago

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.

#15 @DrewAPicture
5 years ago

In 33896:

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

See #33413. See #33701.

#16 @DrewAPicture
5 years ago

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.

#17 @DrewAPicture
5 years ago

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.

#18 @DrewAPicture
5 years ago

In 33899:

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

See #33413. See #33701.

#19 @DrewAPicture
5 years ago

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.

#20 @DrewAPicture
5 years ago

In 33901:

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

See #33413. See #33701.

#21 @GaryJ
5 years ago

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.

#22 @DrewAPicture
5 years ago

In 34392:

Docs: The Widget API is singular.

See #33701.

#23 @DrewAPicture
5 years ago

In 34393:

Docs: The User API is singular.

See #33701.

#24 @DrewAPicture
5 years ago

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.

#25 @DrewAPicture
5 years ago

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.

#26 @DrewAPicture
5 years ago

In 34396:

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

See #33413. See #33701.

#27 @DrewAPicture
5 years ago

In 34397:

Docs: The User API is singular.

See #33701.

#28 @DrewAPicture
5 years ago

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.

#29 @DrewAPicture
5 years ago

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.

#30 @DrewAPicture
5 years ago

In 34400:

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

See #33413. See #33701.

#31 @DrewAPicture
5 years ago

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.

#32 @DrewAPicture
5 years ago

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.

#33 @DrewAPicture
5 years ago

In 34403:

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

See #33413. See #33701.

#34 @DrewAPicture
5 years ago

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.

#35 @DrewAPicture
5 years ago

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.

#36 @DrewAPicture
5 years ago

In 34406:

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

See #33413. See #33701.

#37 @DrewAPicture
5 years ago

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.

#38 @DrewAPicture
5 years ago

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.

#39 @DrewAPicture
5 years ago

In 34409:

Docs: The Comment API is singular.

See #33701.

#40 @DrewAPicture
5 years ago

In 34410:

Docs: The Comment API is singular.

See #33701.

#41 @DrewAPicture
5 years ago

In 34411:

Docs: The Comments subpackage is plural.

See #33701.

#42 @DrewAPicture
5 years ago

In 34412:

Docs: The Users subpackage is plural.

See #33701.

#43 @DrewAPicture
5 years ago

In 34413:

Docs: The Widgets subpackage is plural.

See #33701.

#44 @DrewAPicture
5 years ago

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.

#45 @DrewAPicture
5 years ago

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.

#46 @DrewAPicture
5 years ago

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.

#47 @DrewAPicture
5 years ago

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.

#48 @DrewAPicture
5 years ago

In 34418:

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

See #33413. See #33701.

#49 @DrewAPicture
5 years ago

In 34419:

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

See #33413. See #33701.

#50 @DrewAPicture
5 years ago

In 34420:

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

See #33413. See #33701.

#51 @DrewAPicture
5 years ago

In 34421:

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

See [34168]. See #33701.

#52 @DrewAPicture
5 years ago

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.

#53 @DrewAPicture
5 years ago

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.

#54 @DrewAPicture
5 years ago

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.

#55 @DrewAPicture
5 years ago

In 34427:

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

See #33413. See #33701.

#56 @DrewAPicture
5 years ago

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.

#57 @DrewAPicture
5 years ago

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.

#58 @DrewAPicture
5 years ago

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.

#59 @DrewAPicture
5 years ago

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.

#60 @DrewAPicture
5 years ago

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.

#61 @DrewAPicture
5 years ago

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.

#62 @DrewAPicture
5 years ago

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.

#63 @DrewAPicture
5 years ago

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.

#64 @DrewAPicture
5 years ago

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.

#65 @DrewAPicture
5 years ago

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.

#66 @DrewAPicture
5 years ago

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.

#67 @DrewAPicture
5 years ago

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.

#68 @DrewAPicture
5 years ago

In 34441:

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

See #33701.

#69 @DrewAPicture
5 years ago

  • Type changed from defect (bug) to task (blessed)

#70 @DrewAPicture
5 years ago

In 34498:

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

See #33701.

#71 @DrewAPicture
5 years ago

  • Keywords ongoing added
  • Milestone changed from 4.4 to Future Release

#72 @DrewAPicture
5 years ago

In 35166:

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

See #33701.

#73 @DrewAPicture
5 years ago

In 35167:

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

See #33701.

#74 @DrewAPicture
5 years ago

In 35168:

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

See #33701.

[ci skip]

#75 @DrewAPicture
5 years ago

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.

#76 @DrewAPicture
5 years ago

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.

#77 @DrewAPicture
5 years ago

In 35237:

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

See #33701.

#78 @DrewAPicture
5 years ago

In 35241:

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

See #33701.

#79 @DrewAPicture
5 years ago

In 35262:

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

See #33701.

#80 @DrewAPicture
5 years ago

In 35271:

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

See #33701.

#81 @DrewAPicture
5 years ago

In 35359:

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

See #33701.

#82 @DrewAPicture
5 years ago

In 35387:

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

See #33701.

#83 @DrewAPicture
5 years ago

In 35403:

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

See #33701.

#84 @DrewAPicture
5 years ago

In 35407:

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

See #33701.

#85 @DrewAPicture
5 years ago

In 35558:

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

See #33701.

#86 @DrewAPicture
5 years ago

In 36497:

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

See #34988. See #33701.

#87 @DrewAPicture
5 years ago

In 36498:

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

See #34988. See #33701.

#88 @DrewAPicture
5 years ago

  • Keywords ongoing removed
  • Milestone changed from Future Release to 4.5

Closing in favor of new tickets for individual issues.

#89 @DrewAPicture
5 years ago

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