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. -- Like Music? http://l-i-e.com/artists.htm -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
