[wp-hackers] Re: phpDocumentor (was: Coding style)

[Arne Brachhold]

Hi,

> A multitude of people volunteered, laid out resources, some files were
> even completely documented, but Matt pretty much shot it down, and it
> seems like everyone lost interest again. 

Which is really bad in my opinion. If you never used this type of documentation
you don't know how useful it is. It's not just generating some HTML pages, the
main advantage is that some coding editors (and i don't mean Notepad) may
use the tags to show the docu when you type the function name or hover about it.

I'm primary programming in C# (.net) and I can't imagine what I would do without
IntelliSense. It's so useful if you see the purpose of the parameter you are
currently writing and I don't want to miss it. 

I don't know which editors support these tags, but I'm pretty sure PhpEdit [1]
and Eclipse do it. Personally I'm using VS.php [2], a plugin which adds PHP support
to Visual Studio which is very comfortable if you normally develop in C#.

With good naming guidelines, you don't even need an extra documentation,
because you can just begin typing. If you look for a function to search for posts 
start writing "post_" and you will get a list like "post_add", "post_list" etc. 
Look at the short description with selecting the post_list function using the arrow 
keys and know all about it instantly. 

This is so much faster than looking at the codex, searching through the .php files
or using Google. I really hope that phpDoc will make it into the WordPress SVN.

Best regards,

  Arne Brachhold

[1] http://www.waterproof.fr/
[2] http://www.jcxsoftware.com/vs.php

-- 
mail  himself at arnebrachhold.de
web   http://www.arnebrachhold.de/