On Fri, Apr 5, 2013 at 5:48 AM, Joe Watkins <krak...@php.net> wrote: > 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 ...
I don't want to be a party pooper, but we have enough problems of documenting userland php-src that documenting the internals would simply never be able to keep up with changes/additions, so always be incomplete. Not to mention the fact it is gigantic work to even do the initial docs, and maintaining them no less of a work :) I would love to get the header files commented, like you seem to be proposing (which is confusing, do we really need to ask to add comments? Or an RFC? :)). And adding header files like Sara proposed the other day, with extensive comments, is definitively the way to go. Once the header files are properly documented and understandable by extension writers we could look into ways of embedding that in the online manual somehow. -Hannes -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
