Comments on DragonBe's PHP blog: Quality Assurance on PHP projects - PHPDocumentor

Eclipse does fine without in-code documentation (m...

2011-07-31T01:48:24.973+02:00

Eclipse does fine without in-code documentation (most of the time). The API documentation could be generated without PHPDoc too (eg by using reflection, at least from the moment PHP allows return types and primitives for methods). I'm open for a challenge: provide me with a zend framework class (not 1000 lines long) and I'll try to provide an alternative API generated documentationthat doesn't contain duplication.

@KingCrunch: yes, I'm fully aware of it, but o...

2011-07-30T23:29:39.971+02:00

@KingCrunch: yes, I'm fully aware of it, but on most projects I've been involved with it suits my needs more than enough. But, if you have an article about another documentation generator, let me know and I'll add it here.

@Nestor Rojas: Thanks for your kudos. Much appreciated and very welcome. Do take note of the comments here as PHPDocumentor is quite outdated and other tools are performing better and with less resources. Maybe someone will post an article about it.

@Christian Weiske: You're absolutely right! My bad!

@Lewis: Do you have a blog post on Doxygen? Would like to see how easy it is to set up and integrate with other tools like phing or Ant. Thanks for your kudos, much appreciated.

@Mike van Riel: Hehe, it's because you showed me DocBlox at the DPC uncon and since it's supported by phing I could not include it in my list. Yes, you're absolutely right: PHPDocumentor is not PHP 5.3 ready, but unfortunately I'm not (yet) working on projects with PHP 5.3 code. Do you have an article how to set up DocBlox and how to integrate it with tools like phing or Ant? Would be a great addition to these series.

@Oneway: I know it's quite unbelievable but for the past decade these were the answers I got when I pointed out the missing documentation in the code. I know it's not a perfect world out there, but I started to do something about it by posting articles to show it's not really that difficult to start improving quality assurance. A little step towards awareness and better code.

@Bill Karwin: Hey Bill, thank you for your comment here. I have no experience with the other tools and from time to time I do face the limitations of PHPDocumentor, so I know what you mean. Hopefully Lewis and Mike van Riel will post an article about Doxygen and DocBlox as they seem to know these tools. With their articles I might be able to set up a benchmark system to compare all tools using the same codebase and environment, but as I stated… I haven't got around to figure out the other tools. Maybe the future will give me some spare time.

@Anonymous: If you have great experiences with Docblox, would you write an article on it and link it back to me? Would be very much appreciated.

@Koen: Documentation provided by your tests are very helpful, but I have to argue your statement that it's overrated. API documentation is still the only documentation you can provide to third-party service providers, and don't forget that your IDE uses that same in-code documentation to hint about params, methods and classes. But true, your test methods should be clear and state what's being tested (this is going to be mentioned in another article soon)

Example: Why the hell do you need something like &...

2011-07-29T21:39:12.941+02:00

Example: Why the hell do you need something like "@param float $latitude The latitude of the spot"? Shouldn't that be obvious from the code? If you name your tests with intention revealing names, dito for parameters, why do you need this? You could generate it automatically from the code and everybody would understand. Now it is only duplication, which should be avoided. @Return can be interesting... because PHP doesn't let you specify it (yet).

Can you show me an example where phpdoc gives meaningful info that I can't get from reading the class/method signature (I know PHP doesn't provide primitive type hinting yet and return types).

Doc comments are overrated. On the contrary I beli...

2011-07-29T21:32:02.660+02:00

Doc comments are overrated. On the contrary I believe better documentation could be generated from the test names. Documentation is for algorithms and subtleties you might have forgotten next time you look at it.

See also Robert Martins post here:
http://www.coderanch.com/t/131142/Agile/Javadoc

Great post! I think it's worth pointing out th...

2011-07-29T00:25:28.743+02:00

Great post! I think it's worth pointing out that PHPDocumentor is no longer maintained and does not support PHP 5.3+ features. I've used Docblox and it works great!

Very nice post Michelangelo! Documentation is def...

2011-07-27T18:16:43.272+02:00

Very nice post Michelangelo! Documentation is definitely important for coding productivity. The documentation should contain good information to assist coders to get their work done.

Last time I used Phpdocumentor for a large PHP project, it got overloaded, ran for a very long time, and used all the memory on my workstation until phpdoc finally crashed. I think we need another tool that is more efficient.

I tried getting Doxygen to process PHP code, but couldn't figure out the right options and I ran out of time. Have you gotten Doxygen or the other tools you mention to work as a substitute for phpdoc?

If you have interest in doing that, and comparing them in terms of compatibility, processing time, memory usage, and quality of output, that would be a truly great blog post.

"no time, too many things need to be done bet...

2011-07-27T15:10:11.029+02:00

"no time, too many things need to be done between releases"

That is the only reason i can understand. It's not a good reason, but i can understand how deadlines can cause these things.

All other reasons were quite shocking, to be honest.
If a developer doesn't know why he should be documenting, something is very wrong.
If a company charges extra for documentation (i'm assuming we're talking about code documentation here) there's something even more wrong.

Hey Mike, thanks for mentioning DocBlox! It is wo...

2011-07-27T09:21:43.169+02:00

Hey Mike, thanks for mentioning DocBlox!

It is worth mentioning that phpDocumentor does not support 5.3+ features such as namespaces.
DocBlox and Doxygen both support these new features.

(I am not going to comment on which one does a better job; I am biased ;))

Hi, a good alternative to PHPDocumentor - since ...

2011-07-27T08:13:54.761+02:00

Hi,

a good alternative to PHPDocumentor - since it seems to have been abandonned for more than 3 years now - is Doxygen (http://www.doxygen.org)
It does the same thing, is quite configurable with a simple conf file, and is still maintained.

Oh, and many thanks for your quality assurance series, it is really interesting and useful ! :)

Also see http://blog.liip.ch/archive/2011/07/26/ph...

2011-07-27T08:11:57.297+02:00

Also see http://blog.liip.ch/archive/2011/07/26/phpdoc-compilers-and-inheritdoc.html for a list of PHP documentation generators.

> @param float $latitude The latitude of the sp...

2011-07-27T08:11:03.753+02:00

> @param float $latitude The latitude of the spot
This is a bad description, something that I could figure out from the method name ("findTheSpot") and the parameter name itself.

Better would be:

> @param float $latitude Latitude of the spot in degrees , ranging from +90.0 (north) to -90.0 (south)

Great post! I'm subscribing to it. I'm jus...

2011-07-27T02:27:10.599+02:00

Great post! I'm subscribing to it. I'm just a newbie, but I've been learning php basics for few weeks now. Your post makes me realize how important documentation is on your scripts. Thanks for the post!

I would not recommend PhpDocumentor anymore, becau...

2011-07-27T00:25:53.127+02:00

I would not recommend PhpDocumentor anymore, because its quite outdated and it seems, that there is no development anymore.