Re: cvs: pear /Event_Dispatcher Dispatcher.php Notification.php package.xml /Event_Dispatcher/examples bubbling.php cancel.php notification-class.php
object.php /Event_Dispatcher/tests Console_TestListener.php Dispatcher_testcase.php test.php

Daniel Convissor wrote: >Hi Bertrand: > >On Sat, Feb 05, 2005 at 01:10:38PM -0000, Bertrand Mansion wrote: >> <?php >> // +-----------------------------------------------------------------------+ >> // | Copyright (c) 2005, Bertrand Mansion | >> // | All rights reserved. | > >How about getting ahead of the curve by using the new page level docblocks >from the header comment block proposal in PEPr? > > >> /** >> * 'static property' for Notification object >> */ >> $GLOBALS['_Event_Dispatcher'] = array( > >In order for phpDocumentor to pick up the docblock, it needs to look >like this: > > /** > * 'static property' for Notification object > * @global array $GLOBALS['_Event_Dispatcher'] > */ OK. >> * in {@link Event_Notification} objects. Client objects register > >Here, and throughout the file, @link is misused. It's only for URI's. >@see is used for referencing interal members and the @see tag must be on >it's own, not inline. It is documented this way in the PHPdocumentor tutorial I read. >> * @author Bertrand Mansion <bmansion@mamasam.com> >> * @author Stephan Schmidt <schst@php.net> >> * @copyright 2005 >> * @license >> http://www.opensource.org/licenses/bsd-license.php BSD License >> * @version @VER@ >> * @package Event_Dispatcher > >Please look at the header comment block RFC in PEPr. Copy the class-level >docblock, paste it into your code and then substitute the text appropriate >for your class. The RFC has not been accepted yet AFAIK, this will be changed when the RFC is accepted. >> * @access public >> * @param string Expected notification name, serves as a filter >> * @param mixed A PHP callback >> * @param string Expected contained object class, serves as a >filter >> * @return void >> */ >> function addObserver($callback, $nName = EVENT_DISPATCHER_GLOBAL, $class = >null) > > >Check out the sample file in the coding standards. The @param tags need >the parameter's name in them. AFAIK Phpdocumentor is smart enough to find the parameters name by itself. This is a nice feature, as parameters names might change, without the user being concerned. >The @access goes below the @return, which >needs to get added here. AFAIK, this doesn't affect how Phpdocumentor works. So I'd leave that up to the developer. The idea is that the API documentation be generated right. >Please put line breaks between the @param, >@return and @access sections. I hate to waste space. >Also, plesae wrap the lines (both docblocks >and code itself) when things approach 80 chars. My text editor is not limited to 80 chars. As long as my code is readable and respect Coding standards, it should be ok. It is easy today to get a text editor with this "feature". Anyway, thanks for your comments. Bertrand