Re: How to document 'not implemented, sorta' stuff?

On Jun 7, 2010, at 8:11 AM, G. T. Stresen-Reuter wrote: > On Jun 7, 2010, at 3:47 PM, Philip Olson wrote: > >> >> There are several features in PHP that are "not implemented [yet]", including >> roughly 13 DOM classes. Well, they are sorta (but not really) implemented. >> >> How should we deal with this? > > Just my 2¢ but if something is not (yet) implemented, it doesn't exist and thus > shouldn't be referenced in any end-user documentation. > > I could never tell my clients about x functionality unless it is, well, functional! Doing > otherwise could be interpreted as being less than honest. I mostly agree but the trouble is (as seen in the examples) this stuff is partially implemented. So in the least we should mention them as reserved keywords (at least, the new classes/methods). Or mention them in better detail somewhere, and offer alternatives (and/or allow users to provide them via user comments). I'm not sure the best approach to handling these concerns but am afraid people think "Oh, this is defined so probably just isn't documented yet." which leads them down a time wasting confusing path of testing them out. We could prevent that, somehow. And in the future I don't think "not implemented yet" should be allowed in php-src. Regards, Philip