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
Changed paths:
A phpdoc/doc-base/trunk/scripts/check-missing-initializers.php
Added: phpdoc/doc-base/trunk/scripts/check-missing-initializers.php
===================================================================
--- phpdoc/doc-base/trunk/scripts/check-missing-
initializers.php (rev 0)
+++ phpdoc/doc-base/trunk/scripts/check-missing-
initializers.php 2009-10-23 00:50:03 UTC (rev 289869)
@@ -0,0 +1,71 @@
+<?php
+/*
+Introduction:
+ - This script checks for optional parameters that do not
utilize the <initializer> tag.
+ - Pass in a path and it'll check it. The path might include
all of phpdoc, or a simple extension
+TODO:
+ - Have better output when using -o
+ - Determine what initializer values should be as some cases
aren't clear
+*/
<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
