Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:66996 Return-Path: Mailing-List: contact internals-help@lists.php.net; run by ezmlm Delivered-To: mailing list internals@lists.php.net Received: (qmail 13951 invoked from network); 7 Apr 2013 09:27:11 -0000 Received: from unknown (HELO lists.php.net) (127.0.0.1) by localhost with SMTP; 7 Apr 2013 09:27:11 -0000 X-Host-Fingerprint: 86.14.252.140 cpc3-asfd3-2-0-cust139.1-2.cable.virginmedia.com Received: from [86.14.252.140] ([86.14.252.140:17838] helo=localhost.localdomain) by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP id E8/21-31540-DEB31615 for ; Sun, 07 Apr 2013 05:27:09 -0400 To: internals@lists.php.net,Stas Malyshev Message-ID: <51613BE9.9050504@php.net> Date: Sun, 07 Apr 2013 10:27:05 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130311 Thunderbird/17.0.4 MIME-Version: 1.0 References: <515F397F.8090401@sugarcrm.com> In-Reply-To: <515F397F.8090401@sugarcrm.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Posted-By: 86.14.252.140 Subject: Re: [PHP-DEV] Proposal to document all of Zend and PHP API and SAPIlayers From: krakjoe@php.net (Joe Watkins) On 04/07/2013 12:29 AM, Stas Malyshev wrote: > Hi! > > >> I'm not really sure how documenting (inline) API functions is really >> going to be any different to the prototypes we all put on extension >> functions/methods, or any more time consuming, and I don't see how >> randomness comes into it. > > Just listing function args is not enough usually - in the manual, > functions that have just protos are almost as good as undocumented. I of > course have a bit of skewed point of view - for me, proto is not needed > for API function because I can just look up the function definition > right in the source. But maybe for somebody it would be helpful. > >> I understand having no time but then these are files we all read and >> work with, I don't really understand not being able to take an extra 5 >> minutes here and there when we are already engaged in working with the >> source. > > It's not the question of ability, it's the question of a) if it's useful > and b) having accepted format for doing it. Stas, It is useful if we define the accepted format and encourage people to include useful information, clearly you can look at a function and know it's prototype immediately, but there's no way you know of all 1000 functions, how on earth do you search for a function you do not even know exists. Assuming you find it, which 800/1000 times you will not, reading a prototype doesn't give you all the information you need, it doesn't give you anything. You always end up having to read the source code, where it could be explained in one/two English sentence(s) which your eyes can process at the same time as reading the prototype itself ... I cannot believe it's taken so much discussion just to get nowhere, all I wanted was for someone to take the lead and say "use this standard/format/software", "you may/may not edit headers", "we will deploy the documentation at http://" ... I give up ...