Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:29045 Return-Path: Mailing-List: contact internals-help@lists.php.net; run by ezmlm Delivered-To: mailing list internals@lists.php.net Received: (qmail 83000 invoked by uid 1010); 26 Apr 2007 07:10:24 -0000 Delivered-To: ezmlm-scan-internals@lists.php.net Delivered-To: ezmlm-internals@lists.php.net Received: (qmail 82985 invoked from network); 26 Apr 2007 07:10:24 -0000 Received: from unknown (HELO lists.php.net) (127.0.0.1) by localhost with SMTP; 26 Apr 2007 07:10:24 -0000 Authentication-Results: pb1.pair.com header.from=stas@zend.com; sender-id=pass Authentication-Results: pb1.pair.com smtp.mail=stas@zend.com; spf=pass; sender-id=pass Received-SPF: pass (pb1.pair.com: domain zend.com designates 212.25.124.162 as permitted sender) X-PHP-List-Original-Sender: stas@zend.com X-Host-Fingerprint: 212.25.124.162 mail.zend.com Linux 2.5 (sometimes 2.4) (4) Received: from [212.25.124.162] ([212.25.124.162:15119] helo=mail.zend.com) by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP id 5A/F6-00993-B5050364 for ; Thu, 26 Apr 2007 03:10:22 -0400 Received: (qmail 28670 invoked from network); 26 Apr 2007 07:10:16 -0000 Received: from unknown (HELO ?127.0.0.1?) (10.1.3.179) by internal.zend.office with SMTP; 26 Apr 2007 07:10:16 -0000 Message-ID: <46305057.8060909@zend.com> Date: Thu, 26 Apr 2007 10:10:15 +0300 Organization: Zend Technologies User-Agent: Thunderbird 2.0.0.0 (Windows/20070326) MIME-Version: 1.0 To: Antony Dovgal CC: Gwynne Raskind , internals@lists.php.net References: <97180F0D-CB4C-4071-A859-38059C0DD1FF@wanderingknights.org> <0DFF3A59-3419-4A25-B907-E0E71FD41360@wanderingknights.org> <462FD093.90402@zend.com> In-Reply-To: <462FD093.90402@zend.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [PHP-DEV] Documenting the Zend2 extension API From: stas@zend.com (Stanislav Malyshev) > 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_. Well, in ICU there are two sets of docs - the automatic docs (e.g. http://www.icu-project.org/apiref/icu4c/unum_8h.html) and the human docs (e.g. http://icu-project.org/userguide/formatNumbers.html). Ideally, we should have both - the former is for checking the API, the latter is for actually understanding what it does. There's no way to get the latter doc except for actual person to write it. :) > 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. Same here. -- Stanislav Malyshev, Zend Products Engineer stas@zend.com http://www.zend.com/