plugins.php Documentation for adding new PHPdoc tags

[darkdragon]

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.

[darkdragon]

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

[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?

[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.

[santosj]

Could also do

/

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

[darkdragon]

Correct Patch from Ryan suggestion

[darkdragon]

Completed suggestion from Ryan and added patch.

[ryan]

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

[darkdragon]

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

[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.

[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.

[darkdragon]

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

[darkdragon]

Will hopefully upload correctly.

[darkdragon]

Will hopefully upload correctly.

[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.

[darkdragon]

Fixed as part of recent commit.