Summer of Code Proposal View as Markdown

-----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