Re: Zend API changes

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