Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:29034
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain wanderingknights.org from 208.97.132.81 cause and error)
Mime-Version: 1.0 (Apple Message framework v752.3)
In-Reply-To: <462FD093.90402@zend.com>
References: <97180F0D-CB4C-4071-A859-38059C0DD1FF@wanderingknights.org> <Pine.LNX.4.62.0704252131190.1454@localhost> <0DFF3A59-3419-4A25-B907-E0E71FD41360@wanderingknights.org> <462FD093.90402@zend.com>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
Message-ID: <C74FB334-3BAF-4324-A439-235723F2EB3A@wanderingknights.org>
Content-Transfer-Encoding: 7bit
Date: Wed, 25 Apr 2007 18:32:54 -0400
To: internals@lists.php.net
Subject: Re: [PHP-DEV] Documenting the Zend2 extension API
From: gwynne@wanderingknights.org (Gwynne Raskind)

On Apr 25, 2007, at 6:05 PM, Antony Dovgal wrote:
>> Hmm... For some reason I missed that in my searches. That being  
>> said,  the existence of one doesn't preclude the writing of  
>> another :).  Also, it seems the official documentation in the PHP  
>> manual could use  some serious updating, which I would also be  
>> willing to undertake if  people think that would be more useful.
> Actually I've been recently thinking of adding some kind of  
> documentation to the sources.
> Surely this is not supposed to be something similar to php.net/ 
> manual/, just short descriptions of functions and their arguments,  
> which can be used as a start for the "real" documentation.
> But I wasn't lucky enough to find a utility that would fit my  
> (personal) needs.
>
> Doxygen (which seems to be uses by the majority of F/OSS projects)  
> generates completely unreadable docs.
> Every time I look into ICU docs (generated by Doxygen) I get lost  
> for 10 minutes trying to find a function _by name_.
> In the same time, other tools do not provide such a wide range of  
> output formats as available in Doxygen.
>
> Anyways ZE internals documentation definitely needs serious update  
> and this would be very much appreciated.
> The only problem is that you need to know the internals a bit (or  
> at least want to learn it) to be able to document it, and all the  
> people with this knowledge are busy with other things most of the  
> time..
> You can count on me if you need any help/hints, though.

I've been plugging around writing extensions long enough to have some  
idea of the internals; more than once I've answered a question by  
digging through the Zend sources for the internals of some API. I'm  
willing to at least take a crack at this project; the worst I can do  
is fail :). Would it make sense to ask for CVS karma on the docs now  
or wait a bit?

-- Gwynne, Daughter of the Code
"This whole world is an asylum for the incurable."