Documentaion (Was: [PHP-DEV] PHP File Upload Security Hole - Still No Fix?

Jon Ribbens wrote: > Ron Chmara <ron@opus1.com> wrote: > > > Do you not understand what documentation is and does? Documentation > > > is a guarantee of what works, and what will work in the future. How should > > > I know the answers to these questions? > > Documentation is no guarantee. :-) > In which case it is no documentation. Go to a bookstore. Look in the computer section. Now ask yourself: Why are there all these books, if documentation is so simple as to write one, complete, set, without ever having to revise, republish, rework. Documentation _has_ to be dynamic, and this means that it will not always reflect the current state of the program. There is no program, in existence, that I am aware of, where the entire program is completely documented. None. There are hidden easter eggs, functions hidden because they'll be fixed in the next path, easter eggs, retired function not listed, unknown bugs, etc. > How are people supposed to know how to program PHP? Are they allowed to > go looking through the source code, to find hacky tricks that work in > today's CVS tree, and then complain when they don't work tomorrow? Well, I was grumpy about having to do that myself. So now I'm documenting. > > Indeed, PHP has gone _much_ further than most other languages by having > > real-time, 24x7, documentation correction/addition avialable to > > *every* user who wishes to contribute. > This is great, for people to add examples and tips. It is no use for > providing documentation of what the functions do. You don't seem to realize where a great part of the documentation comes from. Let's take something like, oh, Arrays. Arrays are strange enough to the brand new user that the _concept_ of an array key may be foreign to them. So, there are reference pieces of the documentation, and then added pieces for the different possible _interpretations_. For Perl users (who think in Perl terms) there are "equivalent in Perl" errata notes, etc. To put everything in there, all in one place, would be impossible to do in any reasonale fashion. We'd have to write descriptions for Perl folks, HTML folks, Joe-PHP-is-my-first-language folks, etc. -Bop -- Brought to you from boop!, the dual boot Linux/Win95 Compaq Presario 1625 laptop, currently running RedHat 6.1. Your bopping may vary.