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

On 9 June 2010 16:28, Hannes Magnusson <hannes.magnusson@gmail.com> wrote: > On Mon, Jun 7, 2010 at 18:56, Philip Olson <philip@roshambo.org> wrote: >> >> 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. > > IMO it shouldn't and should be removed. +1 > > -Hannes >