Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:29059
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain zend.com designates 212.25.124.162 as permitted sender)
Message-ID: <4630E895.9060601@zend.com>
Date: Thu, 26 Apr 2007 21:59:49 +0400
User-Agent: Thunderbird 2.0.0.0 (X11/20070326)
MIME-Version: 1.0
To: Marcus Boerger <helly@php.net>
CC: Gwynne Raskind <gwynne@wanderingknights.org>, 
 internals@lists.php.net
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> <1168659886.20070426001225@marcus-boerger.de> <462FD55A.7080809@zend.com> <1377038162.20070426194723@marcus-boerger.de>
In-Reply-To: <1377038162.20070426194723@marcus-boerger.de>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Documenting the Zend2 extension API
From: antony@zend.com (Antony Dovgal)

On 04/26/2007 09:47 PM, Marcus Boerger wrote:
> Hello Antony,
> 
> Thursday, April 26, 2007, 12:25:30 AM, you wrote:
> 
>> On 04/26/2007 02:12 AM, Marcus Boerger wrote:
>>>> 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.
>>> 
>>> Hu? It has a search option if you want. 
> 
>> This one? =)
>> http://www.icu-project.org/apiref/icu4c/search.php?query=strcat
> 
>>> And it has alphabetical lists for
>>> functions, consts, classes, files, modules, whatever. 
> 
>> Maybe there is something wrong with ICU docs (or with me?), but I can't
>> find any alphabetical index of functions.
>> All I can see is a list of functions per file, which is noway convenient.
> 
> Go to: http://www.php.net/~helly/php/ext/spl/
> On the left select 'file members'
> Then on the top of the main part select 'functions'
> That will give you all global functions.

You really think this is good structure?
 
> Now, open 'Class Members' on the left
> Then on the top of the main part select 'functions'
> That will give you a list of all functions,
> each with a list of classes/interfaces implementing them

4 clicks just to get to the list of functions?
No, doxygen is definitely not what I would like to use.

>>> And if that is not enough we could take it's xml output to feed a database and provide a
>>> fulltext search on that.
> 
>> We can also use any of search engines available to search in the result HTML.
>> But the point is that the docs should be well structured enough so that a
>> fulltext search would not be required.
> 
> As i said, from doxygen' XML output we can generate any kind of
> structure we see fit.

-- 
Wbr, 
Antony Dovgal