Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:66992
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Message-ID: <E8.31.15335.9B54F515@pb1.pair.com>
To: internals@lists.php.net
Date: Fri, 05 Apr 2013 22:44:21 +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>
In-Reply-To: <FE.21.57919.BEEAE515@pb1.pair.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: Proposal to document all of Zend and PHP API and SAPI layers
From: krakjoe@php.net (Joe Watkins)

On 04/05/2013 12:00 PM, Joe Watkins 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 user
> land documentation, but there are only scraps of information here and
> there, and then ... the accepted way of working with the source is lxr
> and lots and lots of reading, which is fine, if you require intricate
> knowledge 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 than 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

There seems to be a kind of focus on the things we all know about, 
understandably.

To clarify, I do not mean that we should document hashtable and objects 
and call it a day, I mean that there is more than 1000 exported ZEND_API 
or PHPAPI functions in the source code this evening ... here's a list:

http://pastebin.com/42xFsNQ0

Drop the scrollbar anywhere random, have you written what you land on 
more than once ?? Think it's probably worth the time now ?? Surely 
writing extensions and developing patches and ideas would become much 
easier if this knowledge was easily accessible and documented, surely 
you'll get the time back you put in 10 fold ??

Food for thought ....

Nite ...