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

> 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..


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]

Reply via email to