Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:37179
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: unknown (pb1.pair.com: domain php.net does not designate 85.214.94.56 as permitted sender)
Date: Tue, 22 Apr 2008 18:24:34 +0200
Reply-To: Marcus Boerger <helly@php.net>
Message-ID: <147898898.20080422182434@marcus-boerger.de>
To: Philip Olson <philip@roshambo.org>
CC: Etienne Kneuss <colder@php.net>, "David Coallier" <davidc@php.net>, 
	"Alexey Zakhlestin" <indeyets@gmail.com>, 
	"PHP internals" <internals@lists.php.net>
In-Reply-To: <97A40CDA-69F5-4CD5-8974-276625638380@roshambo.org>
References: <cd5680a20804110816o94cf3d6sd365160ba262ffc9@mail.gmail.com> <b5f7bf6c0804110842l256b8687yb183980e715ef549@mail.gmail.com> <e666c3890804110955i7616b8d3ref5c53349d45e8e8@mail.gmail.com> <97A40CDA-69F5-4CD5-8974-276625638380@roshambo.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-15
Content-Transfer-Encoding: 8bit
Subject: Re: [PHP-DEV] spl documentation
From: helly@php.net (Marcus Boerger)

Hello Philip,

  

Friday, April 11, 2008, 7:29:48 PM, you wrote:


>>> On 11/04/2008, Alexey Zakhlestin <indeyets@gmail.com> wrote:
>>>> I noticed, that http://www.php.net/~helly/php/ext/spl/<http://www.php.net/%7Ehelly/php/ext/spl/ 
>>>> >was updated
>>>> almost a year ago. Is the newer version available anywhere?
>>>>
>>>
>>> Good point, there're so many new things in there. Marcus? Etienne?
>>> Anyone up to do regenerate some docs ?
>>>

>>
>> I've a more recent build that covers DLLists, but only Marcus is  
>> able to
>> upload it to ~helly.
>>
>> I guess a new version will be online as soon as I finish documenting  
>> Heaps
>> and priority queues.

> I think all effort should go into writing real documentation within  
> the phpdoc cvs module instead of unreadable and unofficial doxygen  
> output. Personally I feel the link to the doxygen output should be  
> removed from php.net/spl (but won't) so anyway those are my feelings.  
> Etienne is planning to work on both, which is great, but I encourage  
> everyone to update the official spl documentation and not worry much  
> about doxygen.

Personally I tried for year to get some feedback on getting documentation
to support classes. And we still do not have any acceptable support. So I
went on and provided all documnetation in source code. That said there
should be three easy ways to proceed:

1) delete all my documentation and/or simply ignore what I did and write
whatever documentation you guys want. The code I use for doxygen would
still be useable to understand the code and even allows to replace parts of
SPL on installations of PHP prior to 5.3 where SPL is disabled.

2) Do not change anything at all and continue to improve the documentation
on php.net. Obviously in both versions we might be thinking of keeping or
removing the link to my doxygen stuff.

3) Finally support inheritance in the documentation and either generate
inheritance- and call-graphs for the manual or simply use doxygens xml
format and png output to generate the graphs for the manual. This way we
could even use the docu in the example/replacement code as a basis for the
manual.

Maybe this explains why there is the doxygen stuff. And just once more: I
never tried to overthrow the manual or be better or replace it or whatever.
In fact I only wanted to get the graphs and never got any help to improve
the docs in anyway. So any help to improve the docs are welcome.

Now regarding updates. Updates will come as there is something to update.
The situation is that I could regenerate the doxygen outpiut. But all we
would get is a manual for unreleased features. In other words the current
doxygen output should reflect the current state, that is 5.2.

marcus