Flesh out tag details for the sake of IDEs

[Bob Williams]

Hello,

I recently stumbled on this project while looking for alternatives to
the dead PHPDoc project. I joined the group so that I could make a
suggestion that I think would be very helpful to the PHP community at
large--including those who don't already use docblox--while
simultaneously bringing more visibility to the project.

Basically, I'd like to suggest that the list of tags be fleshed out
with any that are missing, and to thoroughly document the existing
ones--even the ones that aren't yet implemented. I propose this
because as you all know, IDEs rely on PHPDoc comments to provide most
of their auto-completion functionality as well as many static analysis
and refactoring features. As things stand, with PHPDoc lacking support
for all the new goodness in PHP 5.3, there are gaping holes in the IDE
features that are dependent on the docs (for example, identification
of static methods provided by the __callStatic() magic method). Even
if docblox doesn't yet support every tag in documentation-generation,
simply having a well-defined syntax that covers all of modern PHP
would be a huge help, since IDEs can adopt the docblox syntax instead
of implementing proprietary extensions to PHPDoc or suffering from the
functionality gaps resulting from the missing docs. As a bonus, it'll
give people an impression of a more complete, more evolved project
than what they now perceive from the long list mostly unimplemented,
undocumented tags.

Along with adding the syntax, I'd suggest the project reach out to the
IDE teams/companies, such as JetBrains, the NetBeans and Eclipse
projects, and NuSphere. FWIW, I've already made a suggestion to the
JetBrains folks regarding all this via their bug reporter, and I'd be
happy to reach out to them more directly.

Hopefully, I've not offended anyone here or suggested something that's
already well underway. Any and all feedback is welcome.

Thanks,
Bob

[David Buchmann]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

hi bob,

first, i think a good documentation of a documentation tool really makes
sense :-)

standardizing the doc tags is very important indeed. i think besides the
ide manufacturers, there are also the other php documentation tools that
should join that effort. i recently did a blog post [1] (looking for a
specific feature in php doc tools) where i listed some of the tools. the
discussion if php really needs that many different tools for the same
task aside, if they all agree on a common "core" set of tags at least,
that would be great.

now i am in no position to take any decisions for any of the tools, but
am willing to contribute to standardization.

cheers,david

[1]
http://blog.liip.ch/archive/2011/07/26/phpdoc-compilers-and-inheritdoc.html

- --
Liip AG // Agile Web Development // T +41 26 422 25 11
CH-1700 Fribourg // PGP 0xA581808B // www.liip.ch
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk5wYB0ACgkQqBnXnqWBgIstPACffO5QBPFtdz0yYZ6iha0Wt2U6
T60An0YrQIBRdEKz2XMCD1zk2Dk9GdcS
=3IVz
-----END PGP SIGNATURE-----

[Mike van Riel]

Hello Bob and David,

I have been exploring some options in the past week related to that very
suggestion. I will come back to this subject within a couple of days.

Greetings,

Mike van Riel