Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:23160
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Message-ID: <445B1D08.9010001@fischer.name>
Date: Fri, 05 May 2006 11:38:16 +0200
User-Agent: Thunderbird 1.5.0.2 (Windows/20060308)
MIME-Version: 1.0
To: ceo@l-i-e.com
CC: internals@lists.php.net
References: <63515.209.254.223.2.1146784283.squirrel@www.l-i-e.com>
In-Reply-To: <63515.209.254.223.2.1146784283.squirrel@www.l-i-e.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Summer of Code Proposal
From: markus@fischer.name (Markus Fischer)

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Just to support your proposal: yes. Even as a long term PHP user I found
exactly this problem some months ago. Since I'm familiar with the PHP
source and usually have a checkout around somewhere I can quickly check
functions and I was lazy not reporting it; but still it costs me time also.

So, +1 for this idea.

- - Markus

Richard Lynch wrote:
> This may not be sexy enough for Summer of Code, so I thought I'd ask
> for feedback on this idea, and invite some help to formalize it
> better...
> 
> [abstract]
> PHP Docmentation should be even more concise than it already is about
> what is returned in boundary conditions and error conditions.
> 
> The Project will consist of examining virtually all PHP functions and
> their documentation to find under-documented error conditions and
> boundary conditions.
> [/abstract]
> 
> Here's an example that cropped up today on PHP-General:
> 
> set_error_handler is very well-documented, and obviously somebody
> worked very very hard to write the "Return Values" section.  (Yay!)
> 
> "Returns a string containing the previously defined error handler (if
> any), or NULL on error."
> 
> Alas, for the case of no previously defined error handler (and no
> error in setting the handler), it's not really well-defined.
> 
> It might return FALSE for no previously defined error handler.
> 
> Or maybe 0, since it's an "old" function.
> 
> Or it could be '', since it's usually the name of a function being
> returned.
> 
> Or, to be pedantic, it could conceivably even be an empty array if the
> presumption is that "most" users use class/method for error_handler. 
> Obviously, I'm reaching "too" far here to drive home a point, which is
> that it's not actually documented, and this COULD be a valid
> interpretation of the docs.
> 
> So without running a test script, one doesn't know which return value
> to test for to detect no previously defined error_handler, if one
> cares for some reason.
> 
> Worse, one can't be 100% certain that, for reasons not immediately
> apparent, set_error_handler might return FALSE in some PHP release
> versions and 0 in others, as the function got updated/debugged over
> time and release versions.
> 
> Or maybe it could even return FALSE in CGI but '' in other SAPIs, for
> reasons not apparent without reading PHP source.
> 
> Again, this is too far of a reach for this specific example, but there
> are other examples of functions with inherent CGI/SAPI dependencies
> where it's right on target.
> 
> So, one has to write code that is either equally imprecise and relies
> on PHP type juggling for error-handling and boundary conditions, or
> one has to test under many multiple platforms which is impractical, or
> one must read CVS source, with diffs, and hope one can correctly
> stumble through the logic in some cases, to find out what the return
> value really will be.
> 
> Again, I'm pretty sure it's a no-brainer for THIS function to find out
> what the return value is, at least in any given version of PHP -- But
> some more complex functions will not be so obvious.
> 
> So I'm proposing a potential Summer of Code project to seek out these
> boundary conditions and document the behaviour, with PHP release
> version changes as needed.
> 
> In particular, I'm hoping for a more "formal" layout in the Manual of
> some kind of table of error/boundary conditions, and the return
> values, rather than the rather "loose" English statements that
> currently seem to be the norm.
> 
> I know this is a huge task in scale, especially as the paradigms for
> returning 0/1 and TRUE/FALSE changed when TRUE/FALSE were introduced
> to PHP.
> 
> It's also rather large in scope, as determining what are/aren't
> boundary conditions for various functions is possibly beyond the
> experience of a Summer of Code project for a truly complete job to be
> done.
> 
> But what I consider the best documentation on the planet has this
> "hole" I keep falling into:
> 
> What are the return values REALLY going to be in boundary and error
> conditions, as documented behaviour?
> 
> I realize that HUGE strides have been made in this regard, and I am
> *NOT* trying to demoralize nor devalue those efforts!
> 
> I can remember the days when almost NOTHING was documented for return
> types, much less values under error conditions, and adding the
> prototype and mucho documentation has been done.
> 
> I'm proposing a SoC project to "finish off" the last of this long-term
> effort, as much as Docs are ever "finished"
> 
> I also realize that there is nothing (other than my own stupidity and
> lack of time) to stop me from just doing this myself.
> 
> That said, I think it could be a good SoC project, in that it will
> expose the Student to a LOT of the features of PHP, will have them
> writing small but interesting snippets of code using all the
> extensions (.phpt files perhaps), and will make a significant
> worthwhile improvement to the most excellent PHP Documentation.
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.1 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFEWx0I1nS0RcInK9ARApyKAJ9orUkk3aGvsOkt9ho67zI06Dc2iQCgxk/Q
7g6z5OEyLLnumvYEXYOf/ak=
=Y6I7
-----END PGP SIGNATURE-----