Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:66978
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain schlueters.de from 217.114.211.66 cause and error)
To: Ferenc Kovacs <tyra3l@gmail.com>
Cc: Joe Watkins <krakjoe@php.net>, PHP Internals <internals@lists.php.net>
In-Reply-To: <CAH-PCH5wthfykw_=ubazDKnHEQQh9-4VKxWQ9iggJ+mfX_7zVQ@mail.gmail.com>
References: <FE.21.57919.BEEAE515@pb1.pair.com>
	 <CAH-PCH5wthfykw_=ubazDKnHEQQh9-4VKxWQ9iggJ+mfX_7zVQ@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Date: Fri, 05 Apr 2013 14:23:24 +0200
Message-ID: <1365164604.2152.2696.camel@guybrush>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Proposal to document all of Zend and PHP API and
 SAPI layers
From: johannes@schlueters.de (Johannes =?ISO-8859-1?Q?Schl=FCter?=)

On Fri, 2013-04-05 at 14:09 +0200, Ferenc Kovacs wrote:
> 
> I think that it everybody would support that idea, unfortunatelly not
> many
> people have the knowledge AND the time to write up that kind of
> documentation. 

That is the key part. There's no worse documentation than wrong
documentation. Maybe correct documentation only mentioning "useless"
information.

I also think that documenting each and every API leads nowhere, but as
Ferenc said we have to document the structure and help people tofind
what they need.

This all takes time, though, and many seem to prefer adding syntax sugar
and such things over fixing bugs and documenting things.

johannes