RE : [PHP-DEV] Documenting the Zend2 extension API

Hello Gwynne, A suggestion: please add something about exceptions, creating and throwing them, implementing try/catch blocks. I was looking for a way to catch exceptions thrown by some userspace code, and I didn't find anything except the PHP source. Best regards Francois > -----Original Message----- > From: Gwynne Raskind [mailto:gwynne@wanderingknights.org] > Sent: Tuesday, May 29, 2007 11:51 PM > To: internals@lists.php.net > Subject: Re: [PHP-DEV] Documenting the Zend2 extension API > > > On May 8, 2007, at 2:59 PM, Philip Olson wrote: > >> Hi all, just wanted to give you a heads-up that I'm still working > >> on this project; it took me awhile to get the tools properly set > >> up, but I'm plugging away at DocBook XML now, and I'll have a few > >> patches to send in soon, I think. Thanks for all the advice so far! > > Hello Gwynne, > > > > This is excellent news, and feel free to write the doc list if you > > have any questions and/or the IRC channels on efnet (#php.pecl and > > #php.doc). As far as information on the topic goes, let's start a > > list of the current landscape (with ideas to steal from): > > > > - The official docs: http://php.net/manual/internals > > - CodeGen_PECL: http://pear.php.net/package/codegen_pecl > > - A few tutorials: > > http://devzone.zend.com/public/view/tag/extension > > - The book: Extending and Embedding PHP by Sara Golemon > > - Many README files in php-src: > http://cvs.php.net/viewvc.cgi/php-src/ > > - A few talks: http://talks.php.net/index.php/Internals > > - A nice talk: > > http://netevil.org/talks/furlong-golemon-extending- > > php.pdf > > - More talks: http://talks.somabo.de/ > > - A nice talk: http://talks.somabo.de/ > > 200610_zend_conf_php_extension_development.pdf > > - A few examples: > > http://people.apache.org/~nabeel/php/examples/ > > > > Also, let's create a FAQ section dedicated to the topic of > > extension writing. > > This list of links has been extremely helpful to me, Philip; I > appreciate it a lot :). I'm embarassed to say I came down with a bit > of writer's block lately, so I don't have any patches to send > in yet, > unfortunately. However, I would like the opinion of the list on the > avenue I've chosen. > > Basically, it's my estimation that the existing internals > documentation in the manual is not organized very well, nor lends > itself to updating with any manner of ease. The material I've been > writing is a new section dedicated to the API of ZE2, rather than > trying to consolidate all the information for ZE1 (outdated) and ZE3 > (still changing almost every day). My preliminary outline for the > content looks like this (yanked out of my diffs for > manual.xml.in and > subject to change): > > <part id="internals2"> > <title>&Internals2;</title> > &internals2.intro; > &internals2.buildsys.index; <!-- configure options, ext_skel, > config.m4, config.w32, static vs dynamic builds --> > &internals2.structure.index; <!-- ext_skel, module structure, > globals, lifecycle, tests --> > &internals2.memory.index; <!-- management, > persistence, TSRM --> > &internals2.variables.index; <!-- zval, hashtable, references, > constants --> > &internals2.functions.index; <!-- defining, arguments, return > values, passthru, aliasing --> > &internals2.objects.index; <!-- classes, inheritance, > properties, methods, method-function mapping --> > &internals2.resources.index; <!-- defining, creating, > retrieving, > destroying --> > &internals2.ini.index; <!-- defining, retrieving, > changing --> > &internals2.streams.index; <!-- using, wrappers, contexts, > filters --> > <!-- grab the PDO section from &Internals; here? --> > &internals2.apiref.index; <!-- full index of all APIs, > constants, macros, etc. --> > &internals2.ze1.index; <!-- quick list of major > differences, short discussion re: OOP --> > &internals2.ze3.index; <!-- quick discussion of major > changes, some details on Unicode --> > </part> > > My thinking is to document ZE2 completely, since the differences > between 1 and 2 are small enough for the existing internals section > to be of use to anyone writing for 1, and 3 can be more fully > documented later (something I'm willing to take on as well). > > If I'm given a thumbs-down on this way of doing things, I'll > take the > material I've written already and use it to update the existing > internals section, but I think this method has the best chance of > giving people the truly comprehensive online reference we've lacked > for extension writing up to this point. > > -- Gwynne, Daughter of the Code > "This whole world is an asylum for the incurable." > > -- > PHP Internals - PHP Runtime Development Mailing List > To unsubscribe, visit: http://www.php.net/unsub.php > >