-----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----- -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
