Make WordPress Core

Opened 10 years ago

Closed 9 years ago

#33701 closed task (blessed) (fixed)

Standardize core file headers

Reported by: drewapicture's profile DrewAPicture Owned by: drewapicture's profile 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
10 years ago

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

#2 @DrewAPicture
10 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
10 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
10 years ago

In 33871:

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

See #33413. See #33701.

#5 @DrewAPicture
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 years ago

In 34392:

Docs: The Widget API is singular.

See #33701.

#23 @DrewAPicture
10 years ago

In 34393:

Docs: The User API is singular.

See #33701.

#24 @DrewAPicture
10 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
10 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
10 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
10 years ago

In 34397:

Docs: The User API is singular.

See #33701.

#28 @DrewAPicture
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 years ago

In 34409:

Docs: The Comment API is singular.

See #33701.

#40 @DrewAPicture
10 years ago

In 34410:

Docs: The Comment API is singular.

See #33701.

#41 @DrewAPicture
10 years ago

In 34411:

Docs: The Comments subpackage is plural.

See #33701.

#42 @DrewAPicture
10 years ago

In 34412:

Docs: The Users subpackage is plural.

See #33701.

#43 @DrewAPicture
10 years ago

In 34413:

Docs: The Widgets subpackage is plural.

See #33701.

#44 @DrewAPicture
10 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
10 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
10 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
10 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
10 years ago

In 34418:

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

See #33413. See #33701.

#49 @DrewAPicture
10 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
10 years ago

In 34420:

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

See #33413. See #33701.

#51 @DrewAPicture
10 years ago

In 34421:

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

See [34168]. See #33701.

#52 @DrewAPicture
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 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
10 years ago

In 34441:

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

See #33701.

#69 @DrewAPicture
10 years ago

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

#70 @DrewAPicture
10 years ago

In 34498:

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

See #33701.

#71 @DrewAPicture
10 years ago

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

#72 @DrewAPicture
10 years ago

In 35166:

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

See #33701.

#73 @DrewAPicture
10 years ago

In 35167:

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

See #33701.

#74 @DrewAPicture
10 years ago

In 35168:

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

See #33701.

[ci skip]

#75 @DrewAPicture
10 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
10 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
10 years ago

In 35237:

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

See #33701.

#78 @DrewAPicture
10 years ago

In 35241:

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

See #33701.

#79 @DrewAPicture
10 years ago

In 35262:

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

See #33701.

#80 @DrewAPicture
10 years ago

In 35271:

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

See #33701.

#81 @DrewAPicture
9 years ago

In 35359:

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

See #33701.

#82 @DrewAPicture
9 years ago

In 35387:

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

See #33701.

#83 @DrewAPicture
9 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
9 years ago

In 35407:

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

See #33701.

#85 @DrewAPicture
9 years ago

In 35558:

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

See #33701.

#86 @DrewAPicture
9 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
9 years ago

In 36498:

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

See #34988. See #33701.

#88 @DrewAPicture
9 years ago

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

Closing in favor of new tickets for individual issues.

#89 @DrewAPicture
9 years ago

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