On Oct 23, 2009, at 8:46 AM, Richard Quadling wrote:
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?
Interesting. I think it'd work but wonder about the implications and
improper assumptions someone might make if we start doing this. Or, I
could easily be overly paranoid here. What do people think? Use
functions, or write out descriptions in English?
Regards,
Philip
