Re: Re: coding standards: Header Comment Blocks

Personally I find phpdocu output 'pretty', but absolutely and totally useless.. (infact it's annoying to see proposal present this, and not just show phps files) - the comment blocks in the code however are very useful. I do not think that should be mandatory - but changing the example in the manual sounds reasonable.. Regards Alan Tomas V.V.Cox wrote:

Would be nice if a usage example could be there too (ok, at least in the case of light classes). Tomas V.V.Cox Daniel Convissor wrote:

Hello: Klaus raised an interseting point on IRC regarding Header Comment Blocks. For phpDocumentor to work correctly, we really need to have a page-level docblocks. The current standard requires a regular comment at the top of each file: http://pear.php.net/manual/en/standards.header.php Can we please modify the standard to make the header comments to be in docblock format? I'd suggest the following for a standard file: /** * Short description for file * * Long description... * * PHP version 4 or 5 * * This source file is subject to version 3.0 of the PHP license, * that is bundled with this package in the file LICENSE, and is * available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. * If you did not receive a copy of the PHP license and are unable to * obtain it through the world-wide-web, please send a note to * license@php.net so we can mail you a copy immediately. * * @category categoryname * @package packagename

 * @author    Original Author <author@example.com>
 * @author    Another Author <another@example.com>

* @copyright Copyright (c) 1997-2004 The PHP Group * @license http://www.php.net/license/3_0.txt PHP License * @version $Id:$ */ What are your thoughts? Thanks, --Dan