2009/10/23 Philip Olson <phi...@roshambo.org>: > > On Oct 23, 2009, at 3:45 AM, Richard Quadling wrote: > >> 2009/10/23 Philip Olson <phi...@php.net>: >>> >>> philip Fri, 23 Oct 2009 00:50:03 +0000 >>> >>> Revision: http://svn.php.net/viewvc?view=revision&revision=289869 >>> >>> Log: >>> Added a script that finds functions with optional parameters, but are >>> missing the <initializer> tag >>> <snip> > >> Just a thought but not all optional parameters have a discrete default >> value. >> >> One that comes to mind from a recent bug/patch was substr. >> >> The length parameter is optional. >> >> The value though is dependent upon the length of the string. >> >> >> What would be the best way to document this? Currently there is no >> initializer for this parameter. >> >> Is there anything wrong with ... >> >> <initializer>length of $string</initializer> >> >> I don't think we've used descriptions for defaults yet, so what do you >> all think? > > As long as it's terse and makes sense, I think it's okay. Once I stumbled > upon an initialized value that contained a different PHP function name, but > I forget where. > > Before we go wild, we should determine most of the different cases and > define a syntax. Like for example: > - Shorter is better > - Use <parameter> when referring to another parameter (Example: length of > <parameter>$string</parameter>) > - Try not inserting many English words, and discuss usage of entities here. > Some words seem universal now, like "length", is that true? > - Use capitalization? > - ... > > Knowing the default value is useful, and this idea came about while > discussing how we can help IDE developers. However, typically translators > skip this section so increasing the worry is not ideal. Also let's be > careful because this could mean changing over 1500 files as it shows today > that 1558 of 2365 optional parameters lack <initializer>. All thoughts are > welcome. > > Regards, > Philip > > Ref: Discussion moved to phpdoc@lists.php.net > > >
Would <initializer>strlen(<parameter>$string</parameter>)</initializer> be acceptable? -- ----- Richard Quadling "Standing on the shoulders of some very clever giants!" EE : http://www.experts-exchange.com/M_248814.html Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 ZOPA : http://uk.zopa.com/member/RQuadling
