Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:66980
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
To: internals@lists.php.net,=?UTF-8?B?Sm9oYW5uZXMgU2NobMO8dGVy?= <johannes@schlueters.de>
Message-ID: <515EC828.5020403@php.net>
Date: Fri, 05 Apr 2013 13:48:40 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130311 Thunderbird/17.0.4
MIME-Version: 1.0
References: <FE.21.57919.BEEAE515@pb1.pair.com>  <CAH-PCH5wthfykw_=ubazDKnHEQQh9-4VKxWQ9iggJ+mfX_7zVQ@mail.gmail.com> <1365164604.2152.2696.camel@guybrush>
In-Reply-To: <1365164604.2152.2696.camel@guybrush>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Subject: Re: [PHP-DEV] Proposal to document all of Zend and PHP API andSAPI
 layers
From: krakjoe@php.net (Joe Watkins)

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