# Documenting the Zend2 extension API - Thread: https://externals.io/message/29023 - Original archive: https://news-web.php.net/php.internals/29023 - Started by Gwynne Raskind on 2007-04-25T19:21:13+00:00 - Messages: 21 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #29023 — Gwynne Raskind — 2007-04-25T19:21:13+00:00 URL: https://externals.io/message/29023#29023 Given the recent discussion of the lack of real documentation for the Zend API, and the endless links provided to various sources of usually incomplete information, I thought it might be a good idea if someone wrote an actual book on the subject. I'm interested in taking that project upon myself, and I'm wondering what advice anyone has to offer on the idea. -- Gwynne, Daughter of the Code "This whole world is an asylum for the incurable." --- ## #29025 — Derick Rethans — 2007-04-25T19:33:45+00:00 URL: https://externals.io/message/29023#29025 · In reply to: #29023 > Given the recent discussion of the lack of real documentation for the Zend > API, and the endless links provided to various sources of usually incomplete > information, I thought it might be a good idea if someone wrote an actual book > on the subject. I'm interested in taking that project upon myself, and I'm > wondering what advice anyone has to offer on the idea. There is one: http://www.amazon.com/Extending-Embedding-PHP-Developers-Library/dp/067232704X/ref=sr_1_1/102-2890754-1426549?ie=UTF8&s=books&qid=1177529537&sr=8-1 regards, Derick -- Derick Rethans http://derickrethans.nl | http://ez.no | http://xdebug.org --- ## #29029 — Gwynne Raskind — 2007-04-25T21:45:35+00:00 URL: https://externals.io/message/29023#29029 · In reply to: #29025 > > […] > There is one: > http://www.amazon.com/Extending-Embedding-PHP-Developers-Library/dp/ > 067232704X/ref=sr_1_1/102-2890754-1426549? > ie=UTF8&s=books&qid=1177529537&sr=8-1 Hmm... For some reason I missed that in my searches. That being said, the existence of one doesn't preclude the writing of another :). Also, it seems the official documentation in the PHP manual could use some serious updating, which I would also be willing to undertake if people think that would be more useful. -- Gwynne, Daughter of the Code "This whole world is an asylum for the incurable." --- ## #29031 — Antony Dovgal — 2007-04-25T22:05:07+00:00 URL: https://externals.io/message/29023#29031 · In reply to: #29029 > Hmm... For some reason I missed that in my searches. That being said, > the existence of one doesn't preclude the writing of another :). > Also, it seems the official documentation in the PHP manual could use > some serious updating, which I would also be willing to undertake if > people think that would be more useful. Actually I've been recently thinking of adding some kind of documentation to the sources. Surely this is not supposed to be something similar to php.net/manual/, just short descriptions of functions and their arguments, which can be used as a start for the "real" documentation. But I wasn't lucky enough to find a utility that would fit my (personal) needs. Doxygen (which seems to be uses by the majority of F/OSS projects) generates completely unreadable docs. Every time I look into ICU docs (generated by Doxygen) I get lost for 10 minutes trying to find a function _by name_. In the same time, other tools do not provide such a wide range of output formats as available in Doxygen. Anyways ZE internals documentation definitely needs serious update and this would be very much appreciated. The only problem is that you need to know the internals a bit (or at least want to learn it) to be able to document it, and all the people with this knowledge are busy with other things most of the time.. You can count on me if you need any help/hints, though. -- Wbr, Antony Dovgal --- ## #29032 — Marcus Boerger — 2007-04-25T22:12:25+00:00 URL: https://externals.io/message/29023#29032 · In reply to: #29031 Hello Antony, Thursday, April 26, 2007, 12:05:07 AM, you wrote: > > > […] > Actually I've been recently thinking of adding some kind of documentation to the sources. > Surely this is not supposed to be something similar to php.net/manual/, just short > descriptions of functions and their arguments, which can be used as a start for the "real" > documentation. > But I wasn't lucky enough to find a utility that would fit my (personal) needs. > Doxygen (which seems to be uses by the majority of F/OSS projects) > generates completely unreadable docs. > Every time I look into ICU docs (generated by Doxygen) I get lost for 10 > minutes trying to find a function _by name_. > In the same time, other tools do not provide such a wide range of output formats as available in Doxygen. Hu? It has a search option if you want. And it has alphabetical lists for functions, consts, classes, files, modules, whatever. And if that is not enough we could take it's xml output to feed a database and provide a fulltext search on that. > Anyways ZE internals documentation definitely needs serious update and this would be very much appreciated. > The only problem is that you need to know the internals a bit (or at least want to learn it) to be > able to document it, and all the people with this knowledge are busy with other things most of the time.. > You can count on me if you need any help/hints, though. > -- > Wbr, > Antony Dovgal Best regards, Marcus --- ## #29033 — Antony Dovgal — 2007-04-25T22:25:30+00:00 URL: https://externals.io/message/29023#29033 · In reply to: #29032 > > […] > > Hu? It has a search option if you want. This one? =) http://www.icu-project.org/apiref/icu4c/search.php?query=strcat > And it has alphabetical lists for > functions, consts, classes, files, modules, whatever. Maybe there is something wrong with ICU docs (or with me?), but I can't find any alphabetical index of functions. All I can see is a list of functions per file, which is noway convenient. > And if that is not enough we could take it's xml output to feed a database and provide a > fulltext search on that. We can also use any of search engines available to search in the result HTML. But the point is that the docs should be well structured enough so that a fulltext search would not be required. -- Wbr, Antony Dovgal --- ## #29034 — Gwynne Raskind — 2007-04-25T22:32:54+00:00 URL: https://externals.io/message/29023#29034 · In reply to: #29031 > > […] > Actually I've been recently thinking of adding some kind of > documentation to the sources. > Surely this is not supposed to be something similar to php.net/ > manual/, just short descriptions of functions and their arguments, > which can be used as a start for the "real" documentation. > But I wasn't lucky enough to find a utility that would fit my > (personal) needs. > > Doxygen (which seems to be uses by the majority of F/OSS projects) > generates completely unreadable docs. > Every time I look into ICU docs (generated by Doxygen) I get lost > for 10 minutes trying to find a function _by name_. > In the same time, other tools do not provide such a wide range of > output formats as available in Doxygen. > > Anyways ZE internals documentation definitely needs serious update > and this would be very much appreciated. > The only problem is that you need to know the internals a bit (or > at least want to learn it) to be able to document it, and all the > people with this knowledge are busy with other things most of the > time.. > You can count on me if you need any help/hints, though. I've been plugging around writing extensions long enough to have some idea of the internals; more than once I've answered a question by digging through the Zend sources for the internals of some API. I'm willing to at least take a crack at this project; the worst I can do is fail :). Would it make sense to ask for CVS karma on the docs now or wait a bit? -- Gwynne, Daughter of the Code "This whole world is an asylum for the incurable." --- ## #29035 — Antony Dovgal — 2007-04-25T22:51:39+00:00 URL: https://externals.io/message/29023#29035 · In reply to: #29034 > I've been plugging around writing extensions long enough to have some > idea of the internals; more than once I've answered a question by > digging through the Zend sources for the internals of some API. Great! > I'm willing to at least take a crack at this project; the worst I can do > is fail :). Would it make sense to ask for CVS karma on the docs now > or wait a bit? I believe the best way to get karma is to start sending patches. I would also recommend to establish the build environment for the docs (if you don't have one already), it's good idea to test patches before committing. This document should give you a good start: http://doc.php.net/php/dochowto/index.php -- Wbr, Antony Dovgal --- ## #29038 — Steph — 2007-04-25T23:32:06+00:00 URL: https://externals.io/message/29023#29038 · In reply to: #29029 Gwynne, I'm not wanting to be nasty or anything, but: a) Sara is totally expert in this area and you, as yet, are not b) the reason that was ever needed at all is that the open source stuff needs work. If you really want to make things easier for incomers, work on the open source documentation on php.net. Please. It needs serious attention. If you just want glorification, forget it - one with far stronger credentials has gone before. - Steph ----- Original Message ----- From: "Gwynne Raskind" To: Sent: Wednesday, April 25, 2007 10:45 PM Subject: Re: [PHP-DEV] Documenting the Zend2 extension API > > > […] > > Hmm... For some reason I missed that in my searches. That being said, the > existence of one doesn't preclude the writing of another :). Also, it > seems the official documentation in the PHP manual could use some serious > updating, which I would also be willing to undertake if people think that > would be more useful. > > -- Gwynne, Daughter of the Code > "This whole world is an asylum for the incurable." --- ## #29039 — Steph — 2007-04-25T23:34:39+00:00 URL: https://externals.io/message/29023#29039 · In reply to: #29035 - and that will teach me to read to the end of the thread before I respond. What Tony said :) ----- Original Message ----- From: "Antony Dovgal" To: "Gwynne Raskind" Cc: Sent: Wednesday, April 25, 2007 11:51 PM Subject: Re: [PHP-DEV] Documenting the Zend2 extension API > > > […] > > Great! > > […] > > I believe the best way to get karma is to start sending patches. > > I would also recommend to establish the build environment for the docs (if > you don't have one already), it's good idea to test patches before > committing. > This document should give you a good start: > http://doc.php.net/php/dochowto/index.php > > -- > Wbr, Antony Dovgal --- ## #29045 — Stanislav Malyshev — 2007-04-26T07:10:15+00:00 URL: https://externals.io/message/29023#29045 · In reply to: #29031 > Doxygen (which seems to be uses by the majority of F/OSS projects) > generates completely unreadable docs. > Every time I look into ICU docs (generated by Doxygen) I get lost for 10 > minutes trying to find a function _by name_. Well, in ICU there are two sets of docs - the automatic docs (e.g. http://www.icu-project.org/apiref/icu4c/unum_8h.html) and the human docs (e.g. http://icu-project.org/userguide/formatNumbers.html). Ideally, we should have both - the former is for checking the API, the latter is for actually understanding what it does. There's no way to get the latter doc except for actual person to write it. :) > The only problem is that you need to know the internals a bit (or at > least want to learn it) to be able to document it, and all the people > with this knowledge are busy with other things most of the time.. > You can count on me if you need any help/hints, though. Same here. -- Stanislav Malyshev, Zend Products Engineer stas@zend.com http://www.zend.com/ --- ## #29046 — Derick Rethans — 2007-04-26T07:15:08+00:00 URL: https://externals.io/message/29023#29046 · In reply to: #29032 > Hello Antony, > > Thursday, April 26, 2007, 12:05:07 AM, you wrote: > > > […] > > > […] > > > […] > > Hu? It has a search option if you want. And it has alphabetical lists > for functions, consts, classes, files, modules, whatever. And if that > is not enough we could take it's xml output to feed a database and > provide a fulltext search on that. That doesn't make the docs more readable though... Derick -- Derick Rethans http://derickrethans.nl | http://ez.no | http://xdebug.org --- ## #29057 — Marcus Boerger — 2007-04-26T17:47:23+00:00 URL: https://externals.io/message/29023#29057 · In reply to: #29033 Hello Antony, Thursday, April 26, 2007, 12:25:30 AM, you wrote: > > > […] > This one? =) > http://www.icu-project.org/apiref/icu4c/search.php?query=strcat > > […] > Maybe there is something wrong with ICU docs (or with me?), but I can't > find any alphabetical index of functions. > All I can see is a list of functions per file, which is noway convenient. Go to: http://www.php.net/~helly/php/ext/spl/ On the left select 'file members' Then on the top of the main part select 'functions' That will give you all global functions. Now, open 'Class Members' on the left Then on the top of the main part select 'functions' That will give you a list of all functions, each with a list of classes/interfaces implementing them > > […] > We can also use any of search engines available to search in the result HTML. > But the point is that the docs should be well structured enough so that a > fulltext search would not be required. As i said, from doxygen' XML output we can generate any kind of structure we see fit. best regards marcus --- ## #29059 — Antony Dovgal — 2007-04-26T17:59:49+00:00 URL: https://externals.io/message/29023#29059 · In reply to: #29057 > Hello Antony, > > Thursday, April 26, 2007, 12:25:30 AM, you wrote: > > > […] > > > […] > > > […] > > > […] > > Go to: http://www.php.net/~helly/php/ext/spl/ > On the left select 'file members' > Then on the top of the main part select 'functions' > That will give you all global functions. You really think this is good structure? > Now, open 'Class Members' on the left > Then on the top of the main part select 'functions' > That will give you a list of all functions, > each with a list of classes/interfaces implementing them 4 clicks just to get to the list of functions? No, doxygen is definitely not what I would like to use. > > […] > > > […] > > As i said, from doxygen' XML output we can generate any kind of > structure we see fit. -- Wbr, Antony Dovgal --- ## #29209 — Gwynne Raskind — 2007-05-06T01:47:56+00:00 URL: https://externals.io/message/29023#29209 · In reply to: #29035 > > […] > Great! > > […] > I believe the best way to get karma is to start sending patches. > > I would also recommend to establish the build environment for the > docs (if you don't have one already), it's good idea to test > patches before committing. > This document should give you a good start: http://doc.php.net/php/ > dochowto/index.php 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! -- Gwynne, Daughter of the Code "This whole world is an asylum for the incurable." --- ## #29347 — Philip Olson — 2007-05-08T18:59:18+00:00 URL: https://externals.io/message/29023#29347 · In reply to: #29209 > > > […] > > 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. Regards, Philip --- ## #29824 — Gwynne Raskind — 2007-05-27T04:58:31+00:00 URL: https://externals.io/message/29023#29824 · In reply to: #29347 > > […] > 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): &Internals2; &internals2.intro; &internals2.buildsys.index; &internals2.structure.index; &internals2.memory.index; &internals2.variables.index; &internals2.functions.index; &internals2.objects.index; &internals2.resources.index; &internals2.ini.index; &internals2.streams.index; &internals2.apiref.index; &internals2.ze1.index; &internals2.ze3.index; 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." --- ## #29900 — Gwynne Raskind — 2007-05-29T21:51:10+00:00 URL: https://externals.io/message/29023#29900 · In reply to: #29347 > > […] > 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): &Internals2; &internals2.intro; &internals2.buildsys.index; &internals2.structure.index; &internals2.memory.index; &internals2.variables.index; &internals2.functions.index; &internals2.objects.index; &internals2.resources.index; &internals2.ini.index; &internals2.streams.index; &internals2.apiref.index; &internals2.ze1.index; &internals2.ze3.index; 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." --- ## #29911 — Wez Furlong — 2007-05-29T23:41:38+00:00 URL: https://externals.io/message/29023#29911 · In reply to: #29031 We use doxygen for the developer portions of our customer facing manual. The trick is to have it output xml and then massage that to fit into docbook. --Wez. > Doxygen (which seems to be uses by the majority of F/OSS projects) generates completely unreadable docs. > Every time I look into ICU docs (generated by Doxygen) I get lost for 10 minutes trying to find a function _by name_. > In the same time, other tools do not provide such a wide range of output formats as available in Doxygen. > > Anyways ZE internals documentation definitely needs serious update and this would be very much appreciated. > The only problem is that you need to know the internals a bit (or at least want to learn it) to be > able to document it, and all the people with this knowledge are busy with other things most of the time.. > You can count on me if you need any help/hints, though. --- ## #30037 — Philip Olson — 2007-06-02T04:31:04+00:00 URL: https://externals.io/message/29023#30037 · In reply to: #29900 > > > &Internals2; > &internals2.intro; > &internals2.buildsys.index; > &internals2.structure.index; > &internals2.memory.index; > &internals2.variables.index; > &internals2.functions.index; > &internals2.objects.index; > &internals2.resources.index; > &internals2.ini.index; > &internals2.streams.index; > > &internals2.apiref.index; > &internals2.ze1.index; > &internals2.ze3.index; > > > 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. Hello Gwynne, Sounds good. Many times silence on this list means "Sounds good" and internals isn't too keen on defining a structure for documentation... :) So, go for it! Always feel free to ask questions while documenting this and as it all progresses let's be sure internals reviews the information too. Once the information is in manageable and smaller pieces you'll likely have more success getting feedback. And don't be a stranger on #php.pecl @ efnet (IRC) either. Regards, Philip --- ## #30051 — Andi Gutmans — 2007-06-05T02:40:19+00:00 URL: https://externals.io/message/29023#30051 · In reply to: #30037 Btw, the book Derick, Stig and I wrote ("PHP 5 Power Programming") also has a chapter re: writing extensions. While it covers only a subset and has not been updated, I think it does a good job in explaining some of the fundamentals. Reason why I bring this up is because the book is under the open publication license and I believe it might allow you to steal some pieces for the PHP manual. I can get you the exact license if you need (it's been a while so I don't remember exactly which clauses we chose but I think it can be used). Andi > -----Original Message----- > From: Philip Olson [mailto:philip@roshambo.org] > Sent: Friday, June 01, 2007 9:31 PM > To: Gwynne Raskind > Cc: internals@lists.php.net > Subject: Re: [PHP-DEV] Documenting the Zend2 extension API > > > […] > persistence, TSRM --> > > […] > retrieving, > > […] > changing > > […] > section to > > […] > documented > > […] > I'll take the > > […] > > Hello Gwynne, > > Sounds good. Many times silence on this list means "Sounds > good" and internals isn't too keen on defining a structure > for documentation... :) So, go for it! Always feel free to > ask questions while documenting this and as it all progresses > let's be sure internals reviews the information too. Once the > information is in manageable and smaller pieces you'll likely > have more success getting feedback. And don't be a stranger > on #php.pecl @ efnet (IRC) either. > > Regards, > Philip > > -- > To > unsubscribe, visit: http://www.php.net/unsub.php