WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 6 years ago

#5225 closed enhancement (fixed)

plugins.php Documentation for adding new PHPdoc tags

Reported by: darkdragon Owned by:
Milestone: 2.5 Priority: normal
Severity: normal Version: 2.5
Component: Optimization Keywords: has-patch commit phpdoc documentation
Focuses: Cc:

Description

Patch included adds @since information to all functions as well clean up the descriptions and add in more information.

Also adds in @package, @subpackage, and @global PHPdoc tags for helping tell what the functions use and where they belong.

Adds @internal tag with function_name() style as for the suggestion in wp-hackers thread.

Attachments (5)

plugin.phpdoc.diff (19.5 KB) - added by darkdragon 7 years ago.
Final time, corrects @uses, @link tags. Same as old patch.
plugin.phpdoc.2.diff (18.2 KB) - added by darkdragon 7 years ago.
Correct Patch from Ryan suggestion
plugin.phpdoc.3.diff (6.0 KB) - added by darkdragon 7 years ago.
Fixes @since information based off of http://planetozh.com/projects/wordpress-functions-history/table_light.html table
plugin.phpdoc.4.diff (7.0 KB) - added by darkdragon 7 years ago.
Will hopefully upload correctly.
plugin.6278.phpdoc.patch (7.1 KB) - added by darkdragon 7 years ago.
Will hopefully upload correctly.

Download all attachments as: .zip

Change History (16)

darkdragon7 years ago

Final time, corrects @uses, @link tags. Same as old patch.

comment:1 ryan7 years ago

When using an IDE, I configure the IDE to collapse all doc comments down to one line. This one line contains the first line, which is usually the description. That's pretty handy. With this patch the internal line shows up, which is not so handy. Can the description be the first line?

comment:2 santosj7 years ago

Yeah, I'd admit having the @internal function_name() is fairly redundant when you collapse phpdoc comments. The whole purpose is for those who don't have that feature and it would need to be the first line or it becomes worthless. You would then have

/**
 * Short Description
 * 
 * {@internal function_name() }}
 * @access public|private
 *
 * Long Description
 */

Which I don't know, it might not look so awful, but in any case it would also mean that the phpdocs that have the @access tag as the first line would also have to be moved down.

I'll think about this and submit a new patch which resolves your suggestion.

comment:3 santosj7 years ago

Could also do

/

  • {@internal function_name() - }} Short Description */

darkdragon7 years ago

Correct Patch from Ryan suggestion

comment:4 darkdragon7 years ago

  • Keywords has-patch commit added

Completed suggestion from Ryan and added patch.

comment:5 darkdragon7 years ago

  • Keywords phpdoc documentation added

comment:6 ryan7 years ago

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

(In [6276]) phpdoc for plugin API. Props darkdragon. fixes #5225

comment:7 follow-up: darkdragon7 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

Oops, the @since information is incorrect for some functions and changed short description to match Inline Documentation and the rest of Westi patches.

Thanks for committing the previous patch, it helped make this patch smaller.

comment:8 in reply to: ↑ 7 westi7 years ago

Replying to darkdragon:

Oops, the @since information is incorrect for some functions and changed short description to match Inline Documentation and the rest of Westi patches.

Thanks for committing the previous patch, it helped make this patch smaller.

The new patch does not apply at all for me.
Every Hunk is rejected.

comment:9 darkdragon7 years ago

Must be the Windows Line endings. Let me reupload it.

darkdragon7 years ago

Will hopefully upload correctly.

darkdragon7 years ago

Will hopefully upload correctly.

comment:10 darkdragon7 years ago

Okay, the plugin.6278.phpdoc.patch file works now. I had to revert and redo everything back to the way it was. Which thankfully wasn't that much.

In retrospect, it probably wasn't a good idea to say, "Use this entire file." with a conflict.

comment:11 darkdragon6 years ago

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

Fixed as part of recent commit.

Note: See TracTickets for help on using tickets.