Re: Proposal to document all of Zend and PHP API andSAPI layers

On 04/05/2013 01:23 PM, Johannes Schlüter wrote:

On Fri, 2013-04-05 at 14:09 +0200, Ferenc Kovacs wrote:

I think that it everybody would support that idea, unfortunatelly not many people have the knowledge AND the time to write up that kind of documentation.

That is the key part. There's no worse documentation than wrong documentation. Maybe correct documentation only mentioning "useless" information. I also think that documenting each and every API leads nowhere, but as Ferenc said we have to document the structure and help people tofind what they need. This all takes time, though, and many seem to prefer adding syntax sugar and such things over fixing bugs and documenting things. johannes

http://php.net/manual/en/internals2.php This, would be brilliant, if it were anything like complete, and had a searchable API reference, rather than an empty section labelled API reference. What I suggest is that we make an effort to properly define a way to document the source code. Each in our own time we can document the things we interact with, or pick a file whenever we have a spare ten minutes. We might not have a complete set of documentation until version 6 or after, it might even never be complete, much like the PHP manual, but at least it will be on the way, it shouldn't take long for everyone who needs to be aware to become aware, and those that introduce new prototypes or change old ones will know what is expected of them. I shouldn't have said sub-project, what I should have said was, "I propose that we define a standard way to document everything internal", if there is a standard, and the people working on the source are (made) aware of it, it is surely no effort at all to maintain it, once the initial work is done, which doesn't have to happen yesterday. Along with documenting source, we should of course complete the write up of internals2 ... Joe