Automatic @uses in document blocks
Over here we use phpDocumentor which is a good solution for creating nice looking documentation from document blocks. A great thing about phpDocumentor is that all @uses tags become links to what they point to in the output. These links improve the usability of the documentation a lot in my opinion.
These tags are written in a static fashion to link to other documents, an example could be @uses myclass::function(). When using PDT in Eclipse you get the whole document block created for you when you start typing it. What’s left to do is filling in the information that PDT can’t supply, such as comments and the types of arguments. What shouldn’t be impossible is automatic generation of @uses tags too but currently that is not generated.
After doing some documentation for my projects I quickly realized that a lot of time was wasted by manually adding these @uses tags for each function. The solution to the problem is my docblock uses script. Given a list of input folders and corresponding output folders it will parse your whole project and add @uses tags to all your doc blocks.
I don’t add comments to each @uses tag because I feel it’s pretty unnecessary if you just can click the link and see the function with it’s own documentation. That makes this script a perfect thing for me as a last step when I’m finished with all the documentation and only need to put the @uses tags in there.
If you are interested in using the script or studying the source your are welcome to download docblock_uses.zip. Keep in mind that this script can of course not handle the factory pattern.
A pitfall with phpDocumentor (at least the version I am using) is that if you use the @file tag and choose PDF as output the generation of colored code in the PDF simply takes too long time if your project is moderately big.
Related Posts
Tags: PHP