On Jul 1, 2009, at 9:37 PM, Eddie Drapkin wrote:
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?
I recently began the process of moving Reflection from the OOP5 section to reference/reflection so there is that. It's a daunting task so maybe in a week or so it'll be complete. I'm not adding much new information so there will be a lot ready for improvement so please think about it and get ready to add the real documentation. Imagine each class/method having its own page.
Although the manual is fairly structured it's open for new ideas especially since it moved to the book per extension format a year or so ago. So I like the idea of writing better introductions but there is a fine line for it getting too wordy. Feel free to brain storm, discuss, and use Reflection (or any other extension) as a testing ground for new ideas and marketing ploys. In summary: Your ideas sound nice, please continue.
Regards, Philip
