Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:66991
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain sugarcrm.com designates 108.166.43.99 as permitted sender)
Message-ID: <515F397F.8090401@sugarcrm.com>
Date: Fri, 05 Apr 2013 13:52:15 -0700
Organization: SugarCRM
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:17.0) Gecko/20130307 Thunderbird/17.0.4
MIME-Version: 1.0
To: Joe Watkins <krakjoe@php.net>
CC: "internals@lists.php.net" <internals@lists.php.net>
References: <FE.21.57919.BEEAE515@pb1.pair.com>
In-Reply-To: <FE.21.57919.BEEAE515@pb1.pair.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Proposal to document all of Zend and PHP API and SAPI
 layers
From: smalyshev@sugarcrm.com (Stas Malyshev)

Hi!

> 	I am also aware of some documentation included in the PHP manual 
> currently, which should also be completed, and included, with all of the 
> API in a searchable format, just like PHP is in userland.

That is a good idea. Do it :)

> 	Ideally, it would be nice to document the API inline, in source, this 
> means disturbing lots of files, which I'm not keen on, if anyone has any 
> ideas, speak up. The benefit of inline documentation is that if a 

Inline probably wouldn't work that well. To make API understandable,
there is a need in substantial narrative description, which is poorly
compatible with the layout of the source code. Just sticking it in
random place in the sources does not seem beneficial - I think it is
better to have these in central place. Many individual functions become
very easy to figure out once you understand the picture of the API -
i.e., once you know how the HashTable API works, you don't need a lot of
docs to understand what zend_hash_exists() does. So while it may make
sense to describe some complex piece of code inline, describing the API
usually works better separately, IMHO.

> function is changed the changer has the documentation in their 
> peripheral vision, and the chances of documentation getting stale are 
> less likely than if they have to document using some separate system.
> 
> 	I'd like to gauge reaction to this idea, and with it a show of hands, 
> who can actually help ??

Depends on what you mean by "help". If you need somebody who can answer
occasional questions on how something works - I think many people on
this list could do it. I wouldn't mind doing it. If you mean actually
formatting, writing and maintaining docs in proper order - I wouldn't
volunteer for such project since I probably would never have enough
time. It is a significant effort which will need a lot of time, one of
the reasons probably why it wasn't done yet.
-- 
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227