[wp-hackers] questions about PHPdoc and plugins

[Jacob Santos]

Krusty Ruffle wrote:
> I'm trying to wrap my head around PHPdoc, specifically what I need to use to
> document a plugin. I've read the documentation in the codex, but it seems to
> be geared more toward actual WordPress files. I've read the pear
> documentation that the codex links to. I've also looked at many plugins but
> I've noticed that most are not using PHPdoc at all, and those that do have
> limited blocks for some functions.
>
> I think I may be obsessing about this too much and making it harder than it
> is.
>
> My main questions are:
>
> 1) Should I have an opening block for the plugin file itself, if so what
> should it have in it?
> 2) Does anybody know of a plugin that is thoroughly documented with PHPdoc
> that I can download and look at to see what it really looks like in there?
>
> I can look at the core files to see what the Docblocks look like for
> functions and such, but I'm still getting quite befuddled...
>
> Thanks to anyone who can help me out with this or point me in the right
> direction. :)
Mostly, I would say that it takes practice. The documentation in the 
source of WordPress isn't perfect, and a lot has changed to the standard 
in order to make it so. I apologize that the documentation isn't that clear.

I find that visual helps a lot with writing phpdoc style documentation, 
as well as DocBook style documentation for that matter. The reason why 
the wiki works so well, is that you can see it.

Jacob Santos