Re: [PHP-DEV] PHP7 and types - and alternatives to annotation
On 13 July 2015 at 13:23, Lester Caine les...@lsces.co.uk wrote: On 13/07/15 13:12, Marco Pivetta wrote: It's actually the PhpDocumentor folks (and Mike van Riel in first place) pushing forward PSR-5: there's nothing more official than that right now. That's the current standardization path. docblock annotation has been the subject of RFC's as alternatives to other annotation/typing options, and that is the correct platform to carry out that debate rather than on third party tools/standards such as fig and phpdocumentor. Yeap, and these RFCs were rejected due to the fact that for the purposes of php-src it's just comments that can be read as strings via Reflection API. It is not only phdocumentor that uses docblock material, the IDE's I use have no problem with the current docblock material and so there has been no need until now to look at why only phpdocumentor2 has a problem with them ... Most (all?) of those APIs/IDEs/tools are basing their implementation on PHPDocumentor's documentation at http://www.phpdoc.org/docs/latest/index.html, if not directly on PHPDocumentor's components. Not everything in PHP is specified by php-src, nor should be. Actually, pretty much nothing in PHP userland is specified by php-src, and it's probably for the best, since this way you get a choice. In this case you have a simple choice: - not upgrading a stable tool - accepting that there are BC breaks due to the evolution of the ecosystem in the past 10 years, and adapting an old codebase to 10 years of changes Marco Pivetta http://twitter.com/Ocramius http://ocramius.github.com/
Re: [PHP-DEV] PHP7 and types - and alternatives to annotation
On 13/07/15 08:49, Pierre Joye wrote: No, not just my IDE can work. IDE is just the side effect. Proper documentation does much more than that. It seems to go off topic. Docblocks are only slightly related to this thread. The same could be said about annotation (which are widely used too). Coming from a background of 'traditional' php design, all of my code and the libraries I use are documented via phpdoc style annotation which the IDE picks up, and phpdocumentor1 produced a good API description. This was also a GOOD basis to tidy up the various changes through PHP5.x Today much of the infrastructure to make that work is broken and http://lsces.org.uk/wiki/bitweaver+documentation is a starting point at getting the material all up to date. The original documentation had a few errors on the log file, but http://lsces.org.uk/bwdocs2/index.html is the version I've been working on and is listing 3300 errors in the documentation! The next step is to work out how to address those errors, but once again that is unproductive work so perhaps fixing the problems with the older V1 documenter may be a better use of time? The rules phpdocumenter2 follow seem far adrift from the original 'standard'. So it WOULD be nice if there was an approved standard rather than these seeming to be subject to different interpretation all the time. This before addressing the problems of PHP7 migration ... -- Lester Caine - G8HFL - Contact - http://lsces.co.uk/wiki/?page=contact L.S.Caine Electronic Services - http://lsces.co.uk EnquirySolve - http://enquirysolve.com/ Model Engineers Digital Workshop - http://medw.co.uk Rainbow Digital Media - http://rainbowdigitalmedia.co.uk -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DEV] PHP7 and types - and alternatives to annotation
Hi Lester, On 13 July 2015 at 11:36, Lester Caine les...@lsces.co.uk wrote: On 13/07/15 08:49, Pierre Joye wrote: No, not just my IDE can work. IDE is just the side effect. Proper documentation does much more than that. It seems to go off topic. Docblocks are only slightly related to this thread. The same could be said about annotation (which are widely used too). Coming from a background of 'traditional' php design, all of my code and the libraries I use are documented via phpdoc style annotation which the IDE picks up, and phpdocumentor1 produced a good API description. This was also a GOOD basis to tidy up the various changes through PHP5.x Today much of the infrastructure to make that work is broken and http://lsces.org.uk/wiki/bitweaver+documentation is a starting point at getting the material all up to date. The original documentation had a few errors on the log file, but http://lsces.org.uk/bwdocs2/index.html is the version I've been working on and is listing 3300 errors in the documentation! The next step is to work out how to address those errors, but once again that is unproductive work so perhaps fixing the problems with the older V1 documenter may be a better use of time? The rules phpdocumenter2 follow seem far adrift from the original 'standard'. So it WOULD be nice if there was an approved standard rather than these seeming to be subject to different interpretation all the time. This before addressing the problems of PHP7 migration ... Please refer to https://github.com/php-fig/fig-standards/pull/169 Greets, Marco Pivetta http://twitter.com/Ocramius http://ocramius.github.com/
Re: [PHP-DEV] PHP7 and types - and alternatives to annotation
On 13/07/15 11:51, Marco Pivetta wrote: Please refer to https://github.com/php-fig/fig-standards/pull/169 This just adds another level of complication. FIG is not part of the core PHP standards, and some of their choices simply don't fit with legacy code. I suspect that some of the problems I'm currently hitting are because the coding standards I follow do not match FIG ... and I have no intentions of adding that to that todo list ... but I've paid work to get on with currently before I can get back to documentation. -- Lester Caine - G8HFL - Contact - http://lsces.co.uk/wiki/?page=contact L.S.Caine Electronic Services - http://lsces.co.uk EnquirySolve - http://enquirysolve.com/ Model Engineers Digital Workshop - http://medw.co.uk Rainbow Digital Media - http://rainbowdigitalmedia.co.uk -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DEV] PHP7 and types - and alternatives to annotation
On 7/13/2015 4:36 AM, Lester Caine wrote: Coming from a background of 'traditional' php design, all of my code and the libraries I use are documented via phpdoc style annotation which the IDE picks up, and phpdocumentor1 produced a good API description. This was also a GOOD basis to tidy up the various changes through PHP5.x Today much of the infrastructure to make that work is broken and http://lsces.org.uk/wiki/bitweaver+documentation is a starting point at getting the material all up to date. The original documentation had a few errors on the log file, buthttp://lsces.org.uk/bwdocs2/index.html is the version I've been working on and is listing 3300 errors in the documentation! The next step is to work out how to address those errors, Phpdocumentor2? I don't remember the details, but a single patch cleaned up a ton of errors for me. I googled the error message and found a github? pull request or bug report. The best answer is at the bottom of the discussion. As of the last time I loaded it, about 3 months ago, I still had to apply the patch. -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DEV] PHP7 and types - and alternatives to annotation
On 13 July 2015 at 12:20, Lester Caine les...@lsces.co.uk wrote: On 13/07/15 11:51, Marco Pivetta wrote: Please refer to https://github.com/php-fig/fig-standards/pull/169 This just adds another level of complication. FIG is not part of the core PHP standards, and some of their choices simply don't fit with legacy code. I suspect that some of the problems I'm currently hitting are because the coding standards I follow do not match FIG ... and I have no intentions of adding that to that todo list ... but I've paid work to get on with currently before I can get back to documentation. So put a strict no-upgrade-if-without-budget policy on whatever you're working on then? phpdocumentor is also not an official tool: it's built by volunteers and outside the boundaries of php-src. It's actually the PhpDocumentor folks (and Mike van Riel in first place) pushing forward PSR-5: there's nothing more official than that right now. That's the current standardization path. Marco Pivetta http://twitter.com/Ocramius http://ocramius.github.com/
Re: [PHP-DEV] PHP7 and types - and alternatives to annotation
On 13/07/15 13:12, Marco Pivetta wrote: It's actually the PhpDocumentor folks (and Mike van Riel in first place) pushing forward PSR-5: there's nothing more official than that right now. That's the current standardization path. docblock annotation has been the subject of RFC's as alternatives to other annotation/typing options, and that is the correct platform to carry out that debate rather than on third party tools/standards such as fig and phpdocumentor. It is not only phdocumentor that uses docblock material, the IDE's I use have no problem with the current docblock material and so there has been no need until now to look at why only phpdocumentor2 has a problem with them ... -- Lester Caine - G8HFL - Contact - http://lsces.co.uk/wiki/?page=contact L.S.Caine Electronic Services - http://lsces.co.uk EnquirySolve - http://enquirysolve.com/ Model Engineers Digital Workshop - http://medw.co.uk Rainbow Digital Media - http://rainbowdigitalmedia.co.uk -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
