Re: [PHP-DOC] New PECL documentation
Hey guys, Thank you for the feedback. I will get these done asap and let you know. I think I have spent more time writing and fixing documentation than writing the extension itself =) Pieter On 6/7/10 10:08 AM, "Philip Olson" wrote: > > > On Jun 7, 2010, at 12:49 AM, Hannes Magnusson wrote: > >> > On Mon, Jun 7, 2010 at 08:59, Pieter de Zwart >> > wrote: >>> >> Hey guys, >>> >> >>> >> Since build happens Friday, I waited till now so that I can get a solid >>> week >>> >> of feedback before this gets included in the main docs. I committed revs >>> >> 300253 and 300254. >>> >> I would really appreciate it if someone could give it a look over to make >>> >> sure I am following standards and procedures. >>> >> Once that is done, I will finally make release 0.1 of the client... Only >>> >> about 2 months later than expected. >> > >> > >> > The install section contains a detailed info on how to install the >> > library dependency, but then says: >> > + >> > + >> > + download and compile the amqp.so file and add >> > + an extension entry in your >> > php.ini configuration file. >> > + >> > >> > To install the extension itself.. >> > I'm sure we have a standard entity for installing pecl extensions >> > which would be a lot better. >> > Also note the wrong indenting of the programlisting. >> > >> > The ini section seems to use 2 spaces for indenting rather then the >> > standard 1space > > And this is now online (the doc mirror), which may reveal a few more details > like missing return values. > > - http://docs.php.net/amqp > > Be sure to review each prototype too as docgen defaults to 'void' for skeleton > documentation return types, and usually 'string' for parameter types. And I > assume most of your methods should use one of the following within the > returnvalues role: > > - &return.success; (bool) > - &return.void;(void) > > But overall this is an example of "How to release a PECL extension, the right > way." ;) > > Regards, > Philip
Re: [PHP-DOC] New PECL documentation
On Jun 7, 2010, at 12:49 AM, Hannes Magnusson wrote: > On Mon, Jun 7, 2010 at 08:59, Pieter de Zwart > wrote: >> Hey guys, >> >> Since build happens Friday, I waited till now so that I can get a solid week >> of feedback before this gets included in the main docs. I committed revs >> 300253 and 300254. >> I would really appreciate it if someone could give it a look over to make >> sure I am following standards and procedures. >> Once that is done, I will finally make release 0.1 of the client... Only >> about 2 months later than expected. > > > The install section contains a detailed info on how to install the > library dependency, but then says: > + > + > + download and compile the amqp.so file and add > + an extension entry in your > php.ini configuration file. > + > > To install the extension itself.. > I'm sure we have a standard entity for installing pecl extensions > which would be a lot better. > Also note the wrong indenting of the programlisting. > > The ini section seems to use 2 spaces for indenting rather then the > standard 1space And this is now online (the doc mirror), which may reveal a few more details like missing return values. - http://docs.php.net/amqp Be sure to review each prototype too as docgen defaults to 'void' for skeleton documentation return types, and usually 'string' for parameter types. And I assume most of your methods should use one of the following within the returnvalues role: - &return.success; (bool) - &return.void;(void) But overall this is an example of "How to release a PECL extension, the right way." ;) Regards, Philip
Re: [PHP-DOC] Revchecks outdated
On Jun 7, 2010, at 8:22 AM, Mark Wiesemann wrote: > Philip Olson wrote: >> On May 21, 2010, at 1:31 PM, Mark Wiesemann wrote: >>> the revchecks on doc.php.net haven't been updated since May 2nd, e.g.: >>> http://doc.php.net/php/de/revcheck.php?p=translators >>> http://doc.php.net/php/fr/revcheck.php?p=translators >>> >>> Can somebody please take a look at this? >> >> Thanks for the heads up, this should be fixed now. > > Your manual run was successful, but the cron job hasn't successfully run > since then (last update of the revchecks was on May 21). Okay thanks, I'll take a deeper look this time as I probably messed something up when moving the download method from 'svn co' to 'svn export'. Regards, Philip
Re: [PHP-DOC] How to document 'not implemented, sorta' stuff?
On Jun 7, 2010, at 8:11 AM, G. T. Stresen-Reuter wrote: > On Jun 7, 2010, at 3:47 PM, Philip Olson wrote: > >> >> There are several features in PHP that are "not implemented [yet]", >> including roughly 13 DOM classes. Well, they are sorta (but not really) >> implemented. >> >> How should we deal with this? > > Just my 2¢ but if something is not (yet) implemented, it doesn't exist and > thus shouldn't be referenced in any end-user documentation. > > I could never tell my clients about x functionality unless it is, well, > functional! Doing otherwise could be interpreted as being less than honest. I mostly agree but the trouble is (as seen in the examples) this stuff is partially implemented. So in the least we should mention them as reserved keywords (at least, the new classes/methods). Or mention them in better detail somewhere, and offer alternatives (and/or allow users to provide them via user comments). I'm not sure the best approach to handling these concerns but am afraid people think "Oh, this is defined so probably just isn't documented yet." which leads them down a time wasting confusing path of testing them out. We could prevent that, somehow. And in the future I don't think "not implemented yet" should be allowed in php-src. Regards, Philip
Re: [PHP-DOC] Revchecks outdated
Philip Olson wrote: > On May 21, 2010, at 1:31 PM, Mark Wiesemann wrote: >> the revchecks on doc.php.net haven't been updated since May 2nd, e.g.: >> http://doc.php.net/php/de/revcheck.php?p=translators >> http://doc.php.net/php/fr/revcheck.php?p=translators >> >> Can somebody please take a look at this? > > Thanks for the heads up, this should be fixed now. Your manual run was successful, but the cron job hasn't successfully run since then (last update of the revchecks was on May 21). Regards, Mark
Re: [PHP-DOC] How to document 'not implemented, sorta' stuff?
On Jun 7, 2010, at 3:47 PM, Philip Olson wrote: > > There are several features in PHP that are "not implemented [yet]", including > roughly 13 DOM classes. Well, they are sorta (but not really) implemented. > > How should we deal with this? Just my 2¢ but if something is not (yet) implemented, it doesn't exist and thus shouldn't be referenced in any end-user documentation. I could never tell my clients about x functionality unless it is, well, functional! Doing otherwise could be interpreted as being less than honest. HTH Ted Stresen-Reuter http://chicagoitsystems.com
[PHP-DOC] How to document 'not implemented, sorta' stuff?
There are several features in PHP that are "not implemented [yet]", including roughly 13 DOM classes. Well, they are sorta (but not really) implemented. How should we deal with this? Two types of "not implemented": 1. New things, like classes, methods and functions. Easier, and more straight forward 2. Changes, like new/different function parameters Considering some of this stuff is several years old, I'm guessing much of it will _never_ be implemented (e.g., these bogus DOM classes exist as of PHP 5.0.0) so instead they confuse people. But unfortunately these bogus classes are defined, so I suppose they technically exist. Some of this stuff is difficult to find but I imagine an exhaustive list would give people something TODO, but personally I see most of these as bugs in php-src. Thoughts? Here are real world examples: getParameter(); ?> PHP Warning: DOMConfiguration::getParameter(): Not yet implemented lineNumber, PHP_EOL; echo $a->relatedNode; ?> TEST TEST PHP Warning: substr_replace(): Functionality of 'from' and 'len' as arrays is not implemented PHP Warning: substr_replace(): 'from' and 'len' should be of same type - numerical or array PHP Warning: filter_has_var(): INPUT_REQUEST is not yet implemented Regards, Philip
Re: [PHP-DOC] New PECL documentation
On Mon, Jun 7, 2010 at 08:59, Pieter de Zwart wrote: > Hey guys, > > Since build happens Friday, I waited till now so that I can get a solid week > of feedback before this gets included in the main docs. I committed revs > 300253 and 300254. > I would really appreciate it if someone could give it a look over to make > sure I am following standards and procedures. > Once that is done, I will finally make release 0.1 of the client... Only > about 2 months later than expected. The install section contains a detailed info on how to install the library dependency, but then says: + + + download and compile the amqp.so file and add + an extension entry in your php.ini configuration file. + To install the extension itself.. I'm sure we have a standard entity for installing pecl extensions which would be a lot better. Also note the wrong indenting of the programlisting. The ini section seems to use 2 spaces for indenting rather then the standard 1space -Hannes
Re: [PHP-DOC] New PECL documentation
Hey guys, Since build happens Friday, I waited till now so that I can get a solid week of feedback before this gets included in the main docs. I committed revs 300253 and 300254. I would really appreciate it if someone could give it a look over to make sure I am following standards and procedures. Once that is done, I will finally make release 0.1 of the client... Only about 2 months later than expected. Thanks guys! Pieter On 5/27/10 10:02 PM, "Philip Olson" wrote: > > > On May 26, 2010, at 9:16 AM, Pieter de Zwart wrote: > >> > Thanks for the feedback. Ill get those remedied asap. >> > Pieter > > Hello Pieter, > > Also, in case you weren't sure, you do have phpdoc karma. :) > > Regards, > Philip >
