Menu
▾
▴
#55 Method documentation in PHPDoc format
Please add PHPDoc syntax comments for documenting the class and its methods, for example http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/param.html
Related
Why?
Is the existing documentation inadequate, and if so how would rewriting it as phpdoc comment blocks make it better?
When I took over PHPlot, some of the methods were partially documented with "\param type name description" notation - maybe it was doxygen, but it doesn't seem to match the syntax I read about - and as far as I know it was never used. I removed it all. Public methods are now fully documented in the PHPlot Reference Manual, and internal methods are summarized in a separate section there too. The code and its comments remain clean and readable, with comments meant for humans - not programs.
As you can probably tell, I'm not a fan of in-code documentation meta-notation system. Are there reasons behind this request other than something like "compliance with PEAR standards"?
Hi,
I am using an editor called PhpStorm which makes the use of those comments for autocompletion.
Thats my main reasoning...
I did some reading on the PhpStorm IDE you mentioned, and phpDocumentor. I got phpDocumentor and made sure I can use it, at least to make simple XML output.
I think this feature request is worth doing, and I'm going to do it. I'm not going to tie it to a specific release or schedule, though, because it is a lot of work and will be lower priority than anything else (since it doesn't add or improve functionality of PHPlot) - but that doesn't mean it won't get done, because right now I have nothing else open on PHPlot that is higher priority.
I am also not sure what to do with the phpDocumentor output - if anything at all. I can't see it replacing the Reference section in the PHPlot Reference Manual but it would be nice to do something with it. If you ever come across anything that does phpDocumentor to DocBook-XML, I would be very interested.
Work is in progress adding phpdoc comments, with commits on a Subversion branch called 'Code-6_1-phpdoc'. Currently about 100 public methods (of about 180) and both classes have docblocks; none for variables or protected methods yet.
Disappointing to find bugs and limitations in phpDocumentor2, such as @see not working at all, and no way to properly document unnamed parameters of a method that takes variable arguments.
I restarted work on this a few days ago, now that I seem to have a phpDocumentor2 version (2.8.2) that works well enough to check results. All the methods now have docblocks with at least summary, parameters, return (except for deprecated methods, which only have the @deprecated tag). All the class variables have docblock summary lines. I just need to check it over, regression test, then merge it into the trunk.
A few code changes had to be made because of phpDocumentor2 problems with functions taking variable arguments. (They say they added 'variadic' syntax, but it doesn't work for me, and is only for PHP 5.6 anyway.) The code changes should not affect anything.
Implemented in 6.2.0