Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:66997
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.217.173 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <51613BE9.9050504@php.net>
References: <FE.21.57919.BEEAE515@pb1.pair.com>
	<515F397F.8090401@sugarcrm.com>
	<51613BE9.9050504@php.net>
Date: Sun, 7 Apr 2013 13:10:14 +0200
Message-ID: <CAEZPtU5to7Vw_UytapKCeA4Wf5zmPcc5vEbG=HZp9FjGyA_Gxw@mail.gmail.com>
To: Joe Watkins <krakjoe@php.net>
Cc: PHP internals <internals@lists.php.net>, Stas Malyshev <smalyshev@sugarcrm.com>
Content-Type: text/plain; charset=ISO-8859-1
Subject: Re: [PHP-DEV] Proposal to document all of Zend and PHP API and SAPIlayers
From: pierre.php@gmail.com (Pierre Joye)

hi,

On Sun, Apr 7, 2013 at 11:27 AM, Joe Watkins <krakjoe@php.net> wrote:

>     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 ...

The more I look at this problem (and have looked at it quite a lot of
time), the more I think we should enforce one tool for inline
docblock. Doxygen or other (I use cxref, small and perfect for C)
would do it, generate docs on release/snaps and be done with that. But
the current situation simply increases the clue gap between those
implementing internal functions and those using them. Btw, I do not
blame anyone, we are all lazy, and I am the laziest :)

Cheers,
--
Pierre

@pierrejoye