4

I have an large php project. I used to document it with NaturalDocs, but I didn't include the documentation generation in the build process for a long time ( years ).

I recently started using composer and looked into PSR. The only standard way to document my code seems to be docblocks for phpdocumentor.

Since my code is only in part object oriented and contains much procedural files, I cannot only rely on documenting classes and functions, but I have alot of file level documentation.

It turns out that page level docblocks are not well supported in phpdocumentor ( see https://stackoverflow.com/questions/26925742/page-level-docblocks-and-phpdocumentor-templates ). Therefore I'm really stuck now.

To conclude my questions :

Does it make sense to document non object oriented code with docblocks and phpdocumentor ? Is phpdocs a good choice here ? Is my approach to professionnalize the documentation of our project viable or is it somehow flawed ?

  • 1
    Would moving to object oriented code be a solution? – Arseni Mourzenko Nov 17 '14 at 13:11
  • @MainMa In the long run, yes. But for the moment we do not have the ressources to do it. Also, it's hard to immagine, how to squeeze that code in a object model. – Lorenz Meyer Nov 17 '14 at 13:28
  • 3
    doxygen might be a choice as well, but I don't know how well it can compete with those tools mentioned already. – Christian Hujer Nov 26 '14 at 14:39
  • 2
    I looked into doxygen, and it works out of the box with much more features than phpDocumentor. – Lorenz Meyer Nov 27 '14 at 17:30
3
+50

I still think it makes sense to stick to phpDoc to document PHP code. It is the standard recommended by the php PSR project. It is also generalized into the annotations concept, as it is used for instance in Doctrine. Another argument for phpDoc is that Javascript and many other languages have it's analoguos commenting system.

After much time spent to try to get phpDocumentor work, I generated the documentation with Doxygen. There are clear advantages over phpDocumentor:

  • It works out of the box. There is no need to deal with hosts of bugs.
  • Flexibility: there are many more options with doxygen.
  • Page level docblocks work out of the box (starting the docblock with @file).
  • It is possible to document all entities, even thoug they have no doc. This allows you to get a complete doc of all classes, functions and vars in the project, without starting to document. This goes with the DRY principle and allows you only to document manually what is important. You can document the bigger picture and let Doxygen enumerate all function arguments...
  • It's faster to generate the doc
  • The doc is nicer.

The only drawback I found is that you cannot stick 1 to 1 to the PSR-5 standard proposal :

  • @var is deprecated in favor of @type, but doxygen understands only @var.
  • @file is necessary, but doesn't exist as tag phpDoc.

But phpDocumentor does not honour phpDoc standard neither (e.g. the recommended way to describe hashes is not understood by phpDocumentor).

Conclusion

Having a complete documentation of the code is a must. It simplifies work and gives relief.

For me documentation is crucial, therefore it is difficult to understand that PHP Framework Interop Group issues recommendations about documentation, that no documentation generator compies to.

  • Excellent work, Lorenz. I'm in much the same situation as you and found phpDocumentor seriously lacking. doxygen is simply leaps and bounds ahead, as you've described. – Bobby Jack Mar 7 '16 at 15:36

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.