How to move php documentation closer to standards?

Question

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 ?

Answer 1

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.