Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:66983
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.215.49 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <515EC828.5020403@php.net>
References: <FE.21.57919.BEEAE515@pb1.pair.com>
	<CAH-PCH5wthfykw_=ubazDKnHEQQh9-4VKxWQ9iggJ+mfX_7zVQ@mail.gmail.com>
	<1365164604.2152.2696.camel@guybrush>
	<515EC828.5020403@php.net>
Date: Fri, 5 Apr 2013 06:16:28 -0700
Message-ID: <CADNQb0Ukn0ZvZe+rKAmeCtQ7R602x0fzjWgTtJon8WBFGV__dw@mail.gmail.com>
To: Joe Watkins <krakjoe@php.net>
Cc: PHP Development <internals@lists.php.net>, =?UTF-8?Q?Johannes_Schl=C3=BCter?= <johannes@schlueters.de>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Subject: Re: [PHP-DEV] Proposal to document all of Zend and PHP API andSAPI layers
From: hannes.magnusson@gmail.com (Hannes Magnusson)

On Fri, Apr 5, 2013 at 5:48 AM, Joe Watkins <krakjoe@php.net> wrote:
> On 04/05/2013 01:23 PM, Johannes Schl=C3=BCter 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 afte=
r,
> it might even never be complete, much like the PHP manual, but at least i=
t
> 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 propos=
e
> 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