WordPress.org

Make WordPress Core

Opened 8 years ago

Closed 8 years ago

#24886 closed defect (bug) (fixed)

Functional Docs: wp-includes/load.php

Reported by: ericlewis Owned by:
Milestone: 4.0 Priority: normal
Severity: normal Version:
Component: Bootstrap/Load Keywords: has-patch
Focuses: docs Cc:

Description


Attachments (3)

24886.diff (12.0 KB) - added by ericlewis 8 years ago.
24886.1.diff (13.5 KB) - added by ericlewis 8 years ago.
24886.2.diff (15.5 KB) - added by DrewAPicture 8 years ago.

Download all attachments as: .zip

Change History (13)

@ericlewis
8 years ago

#1 @ericlewis
8 years ago

In attachment:24886.diff, a rough run through of all inline documentation and docblocks.

Beginning this, I realize a (relatively) formalized syntax specific for WP core documentation would be helpful. There is a Pear Docblock comment standards which has some examples that can be considered.

#2 follow-up: @kpdesign
8 years ago

The inline documentation standard from the Codex is being rewritten, and will be included in the Core Contributor Handbook (I need to incorporate DrewAPicture's suggested changes).

There's also a PHPDoc Tags Guide which lays out what the most-used tags are in WordPress inline docs, and how they are used. The Pear comment standards you referenced were used in creating the inline documentation standard currently in the Codex.

#3 in reply to: ↑ 2 @ericlewis
8 years ago

Replying to kpdesign:

The inline documentation standard from the Codex is being rewritten, and will be included in the Core Contributor Handbook (I need to incorporate DrewAPicture's suggested changes).

I'd be glad to help with the effort, I'll check in with the docs team during the weekly chat this week.

@ericlewis
8 years ago

#4 @ericlewis
8 years ago

In attachment:24886.1.diff

reintroduce @globals declarations
remove unused global $text_direction declaration in wp_load_translations_early()

#5 follow-up: @DrewAPicture
8 years ago

Notes on 24886.1.diff:

This was generated before the inline docs standards were in place so a few things will need to change across the board:

  • Periods on functional short descriptions
  • Remove any new @uses tags
  • @global, @param, @return need ending periods.
  • space alignment types then $vars, then descriptions

Also:

  • s/multisite/Multisite
  • s/blog/site

#6 in reply to: ↑ 5 @ericlewis
8 years ago

I also added a bunch of @global tags in here. What did we decide about documenting globals? It was spoken about in IRC a few weeks ago, and @nacin suggested that @globals are "really easy to abuse," and @uses should be used extremely sparingly. I think that constitutes a decision for @uses, we should mention it in our PHP Inline Doc standards. However the use of @globals is still vague since we didn't make a decision on its suggested use.

Replying to DrewAPicture:

  • s/multisite/Multisite

Should Multisite always be capitalized? Core inline documentation is split in this regard. The codex article Create A Network goes back and forth between capitals and non-caps. Using the term Multisite is generally an abbreviation for WordPress Multisite, so I would say let's change all our naming conventions here to capitals across the board.

#7 @DrewAPicture
8 years ago

  • Keywords has-patch added
  • Summary changed from Improve wp-includes/load.php inline documentation to Functional Docs: wp-includes/load.php

#8 @nacin
8 years ago

  • Component changed from Inline Docs to Bootstrap/Load
  • Focuses docs added

@DrewAPicture
8 years ago

#9 @DrewAPicture
8 years ago

  • Milestone changed from Awaiting Review to 4.0
  • Type changed from enhancement to defect (bug)
  • Version 3.5.2 deleted

#10 @DrewAPicture
8 years ago

  • Resolution set to fixed
  • Status changed from new to closed

This is fixed as of [28656]. Looks like it missed posting/closing the ticket.

Props ericlewis, DrewAPicture.

Note: See TracTickets for help on using tickets.