On Fri, 4 May 2001, Hartmut Holzgraefe wrote:
> Zeev Suraski wrote:
> >
> > Hope is always a good thing :)
> > There's a good starting point already, people are more than welcome to
> > extend it.
>
> besides all political/philosophical issues (licensing and such ...)
>
> i am talking about a *reference* documentation, not a manual or howto
>
I'll agree this is needed (however, I no longer have an impetus to create
it :)
> neither the book chapter you defined to be the official documentation
> nor the readme files describe the complete api
>
> e.g. it's very hard to get the clue what all the *FETCH macros are good
> for from the so called official documentation
>
do you still need an explanation? the source makes it pretty clear to
me...
> thats why i talk about a *reference* documentation that explains the
> API funktion by function in manpage style
>
Well maybe not manpage style. I think there should be some Javadoc-like
comments in the Zend source, the same way the apache portable runtime is
documented or state threads library is (yeah, yeah, I know, don't end
sentences with prepositions :).
> i've been into all this for more than a year now and i still have
> lots of open questions about a lot of things even after doing a *lot*
> of "Read the source, Luke" and this is, well, lets say 'suboptimal'
>
Well what are the questions, you can always ask them on the list in the
absence of some API documentation.
> for stuff as complex (and as stuffed with preprocessor magic) like
> the Zend Engine it is usually a very bad idea to have people write
> the docs for it that didn't build it
>
I don't know about that. Most of the zend engine is pretty clear to me,
especially so the API portions (ok, zend_alloc.c is a bit gnarly, but the
rest of the engine is pretty clear :)
> thats like playing "Stille Post" (afaik this game is called "telephone"
> in the US) or like babelfish translating a text from one language to
> another and back: very funny results but not very helpfull
>
Perhaps describing the internals of the engine would be like that, but the
common api is pretty easy to use and describe. I might not have said this
a year ago, but..
.Sterling
--
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
To contact the list administrators, e-mail: [EMAIL PROTECTED]
