Hey there! I'm (slowly *shakes fist*) working on reworking the Reflection documentation to be more friendly, organized, etc. etc. and more closely resemble any of the other multitude of multi-class pacakges. Long story short, I'm workign right now on the Introduction, and what can go there? I've basically limited what I'd like to put there into several sections:
1) An introduction to reflection in general terms, similar to what already exists, but more elaborate 2) A brief decription of the general usage in PHP 3) "Why use Reflection?" - an analysis of realistic cases where Reflection is useful, perhaps linking ot external resources for further research (wikipedia, probably) And basically, I've not seen (not that it doesn't exist), an example of #3 in use in the PHP manual any where, nor can I find any sort of RFC or guideline forbidding it. So, my question is whether or not that sort of documentation is allowed or not. As I was learning PHP, I came across documentation for extensions that seemed useless or silly to me, at the time and often went off into research tangents trying to figure out why Tidy exists (really D=) or what the viable use cases for memcached were or why opcode caches exist, etc. etc. All in all, it did me a lot of good as a web developer to do that research, but I think someone a lot less diligent or insane would have read the synopsis, though "man, fuck this, it's useless" and moved on, without expanding their horizons in PHP because of no immediate need, which is A Damn Shame (pardon the french, all around). I think that if it's allowed, sections like "What's it for?" whether as their own "page" or just a paragraph in the introduction, even if they're short, can't possibly be a bad thing for a budding developer. But then again, it could also be seen as documentation cruft and not absolutely necessary. What are your thoughts? How should I continue?
