Re: Zend API changes

Sterling Hughes wrote: > > 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... no, its clear to me to, although it took some time of browsing around on lxr.php.net and bonsai.php.net to get the message but the fetch macros are rather essential IMHO and AFAIR they were mentioned only once in a subsentence (or even in brackets) without further description > > 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 :). any reference style will do as long as one can find the answer to 'wtf does zend_xxx() do?' quickly, something embeded in the source the way e.g. javadoc does it would sure be nice > > 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. no questions i need answers for (yet), just a lot of loose ends > > 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 :) it may be pretty clear to you, it is clear enough for me now, but the usual c coder wanting to code an extensions most likely doesn't like the idea of looking for clues on lxr.php.net and bonsai.php.net as soon as he has reached a point where the documentation doesn't help him anymore > > 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.. imagine someone with an intermediate knowledge of C wanting to code an extension. his knowledge might be good enough to integrate his stuff, but with the current state of the documentation he will most likely not do it as it would involve a lot of extra source reading and figuring things out too a lot of people, especially those that do not use php themselves, will give up on this or will produce ugly code and this does not only hurt php, it especially hurts Zend IMHO how should one put trust in the products or especially in the support programm of a company that is not able or willing to provide proper docs for its central product that all the other ones are built upon? PS: maybe i've been bitten by bad API documentation to much in the last few weeks (non-php products in this case) -- Hartmut Holzgraefe hartmut@six.de http://www.six.de +49-711-99091-77