Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:66977
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.210.178 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <FE.21.57919.BEEAE515@pb1.pair.com>
References: <FE.21.57919.BEEAE515@pb1.pair.com>
Date: Fri, 5 Apr 2013 14:09:59 +0200
Message-ID: <CAH-PCH5wthfykw_=ubazDKnHEQQh9-4VKxWQ9iggJ+mfX_7zVQ@mail.gmail.com>
To: Joe Watkins <krakjoe@php.net>
Cc: PHP Internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=14dae93408a552efa404d99bf747
Subject: Re: [PHP-DEV] Proposal to document all of Zend and PHP API and SAPI layers
From: tyra3l@gmail.com (Ferenc Kovacs)

--14dae93408a552efa404d99bf747
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

On Fri, Apr 5, 2013 at 1:00 PM, Joe Watkins <krakjoe@php.net> wrote:

> Morning All,
>
>         Further to discussion in IRC this morning, I'd like to propose
> what amounts to, I guess, a sub-project to properly document everything,
> starting with everything declared ZEND_API in /Zend.
>
>         We put a lot of effort into the generation and maintenance of use=
r
> land documentation, but there are only scraps of information here and
> there, and then ... the accepted way of working with the source is lxr an=
d
> lots and lots of reading, which is fine, if you require intricate knowled=
ge
> of every part of the API you are interacting with, which normally you do
> not, usually it is enough to know of it's existence, it's usage and
> implementation is either obvious or irrelevant in the vast majority of
> cases, should the function prototype be documented.
>
>         I am also aware of some documentation included in the PHP manual
> currently, which should also be completed, and included, with all of the
> API in a searchable format, just like PHP is in userland.
>
>         Ideally, it would be nice to document the API inline, in source,
> this means disturbing lots of files, which I'm not keen on, if anyone has
> any ideas, speak up. The benefit of inline documentation is that if a
> function is changed the changer has the documentation in their peripheral
> vision, and the chances of documentation getting stale are less likely th=
an
> if they have to document using some separate system.
>
>         I'd like to gauge reaction to this idea, and with it a show of
> hands, who can actually help ??
>
> Thanks for listening :)
>
> Joe
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>
Hi,

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.
Keeping it up-to-date would be less of a problem, as we could put the
burden of updating the docs on that person changing the code.
Personally I think it would be nice if we could have inline comments in the
code, and using doxygen (or similar) tool to generate some html
representation for the docs (helly used this for documenting spl:
http://www.php.net/~helly/php/ext/spl/ ).
But we also need to have some more high level documentation, where we
introduce the concepts and how the pieces fit together, that could be under
http://php.net/internals2
I'm curious what others think though.

--=20
Ferenc Kov=C3=A1cs
@Tyr43l - http://tyrael.hu

--14dae93408a552efa404d99bf747--