Re: PHPDocumentor manual and @throws tag

On Nov 20, 2007 3:11 AM, Laurent Laville <pear@laurent-laville.org> wrote: > 496 | ERROR | @throws tag must contain a comment > > I look at official manual [1] and don't see any entry. Well I suppose it's > missing. Could we have some information about this phpdoc tag, and > how to document it. > PhpDocumentor does not recognize @throws as a specific tag... it is just * allowing* it as a *custom *tag (you can see it already listed in the * _phpDocumentor_allowed_tags* section in *phpDocumentor.ini* file), and so would treat it as a generic *@tag description* format. If you were to remove "throws" from that listing in the INI file, then PhpDocumentor would throw a warning about it being an unknown tag. > Actually, I set in code, for example : > > * @throws PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND > * @access public > * @since 0.1 > > So I suppose comment is missing right after constants > PEAR_PACKAGEFILEMANAGER_* > That Codesniffer error does indeed sound like it is specifically targeting the *@throws* tag as if it is a specific tag requirement, and wants a comment/description piece after the exception type (*@throws ExceptionType some description now*). So, I'm guessing it wants something like this: - @throws PEAR_PACKAGEFILEMANAGER_NOSTATE if no $state was passed to the function - @throws PEAR_PACKAGEFILEMANAGER_NOVERSION if no $version was passed to the function - @throws PEAR_PACKAGEFILEMANAGER_NOPKGDIR if no $pkgdir was passed to the function I don't think that Codesniffer will complain if the descriptions are all not in line with each other (like I did above), but I also don't think it will complain if you *do* line them up like I did. Again, there's nothing about @throws in the PhpDocumentor manual because it is not a true specific tag that PhpDocumentor recognizes. -- CRB Let me introduce you to my very own DMCA-protected encryption key: BC 1B 64 4A 8D DE 49 E8 C3 7D CC EE 1A AD EE F5 (compliments of Freedom-to-Tinker http://www.freedom-to-tinker.com/?p=1155)