Ticket #5225 (closed enhancement: fixed)

Opened 1 year ago

Last modified 10 months ago

plugins.php Documentation for adding new PHPdoc tags

Reported by: darkdragon Assigned to: anonymous
Priority: normal Milestone: 2.5
Component: Optimization Version: 2.5
Severity: normal Keywords: has-patch commit phpdoc documentation
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

plugin.phpdoc.diff (19.5 kB) - added by darkdragon on 10/18/07 03:49:13.
Final time, corrects @uses, @link tags. Same as old patch.
plugin.phpdoc.2.diff (18.2 kB) - added by darkdragon on 10/19/07 01:48:59.
Correct Patch from Ryan suggestion
plugin.phpdoc.3.diff (6.0 kB) - added by darkdragon on 10/20/07 00:36:09.
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 on 10/20/07 18:02:42.
Will hopefully upload correctly.
plugin.6278.phpdoc.patch (7.1 kB) - added by darkdragon on 10/20/07 18:13:26.
Will hopefully upload correctly.

Change History

10/18/07 03:49:13 changed by darkdragon

  • attachment plugin.phpdoc.diff added.

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

10/18/07 05:58:03 changed by ryan

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?

10/18/07 13:44:22 changed by santosj

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.

10/18/07 13:45:47 changed by santosj

Could also do

/**

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

10/19/07 01:48:59 changed by darkdragon

  • attachment plugin.phpdoc.2.diff added.

Correct Patch from Ryan suggestion

10/19/07 01:52:19 changed by darkdragon

  • keywords set to has-patch commit.

Completed suggestion from Ryan and added patch.

10/19/07 01:53:12 changed by darkdragon

  • keywords changed from has-patch commit to has-patch commit phpdoc documentation.

10/19/07 17:45:08 changed by ryan

  • status changed from new to closed.
  • resolution set to fixed.

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

10/20/07 00:36:09 changed by darkdragon

  • attachment plugin.phpdoc.3.diff added.

Fixes @since information based off of http://planetozh.com/projects/wordpress-functions-history/table_light.html table

(follow-up: ↓ 8 ) 10/20/07 00:37:38 changed by darkdragon

  • status changed from closed to reopened.
  • resolution deleted.

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.

(in reply to: ↑ 7 ) 10/20/07 09:31:31 changed by westi

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.

10/20/07 17:36:16 changed by darkdragon

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

10/20/07 18:02:42 changed by darkdragon

  • attachment plugin.phpdoc.4.diff added.

Will hopefully upload correctly.

10/20/07 18:13:26 changed by darkdragon

  • attachment plugin.6278.phpdoc.patch added.

Will hopefully upload correctly.

10/20/07 18:15:16 changed by darkdragon

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.

12/06/07 12:31:37 changed by darkdragon

  • status changed from reopened to closed.
  • resolution set to fixed.

Fixed as part of recent commit.