Recently I found myself with a task to update an outdated documentation. At first I wanted to do it manually, but then I asked myself, why don’t generating this documentation automatically? As a programmer I have to automate everything. It just needs the right approach to do it.
As you may remember, documenting source code while programming is the best way to do it. Beside that, it’s also a good approach to use PHP annotations.
They offering you a way to handle PHP Annotations programmatically, using Doctrine Annotations. You can even create your own Annotation classes.
So I used Doctrine Annotations in combination with Reflection on Doctrine Entities to collect all needed informations. A converter class is doing this job by putting the informations into a document object. In the next step the main process (a Symfony Command) is passing the document object to a function which writes a OpenDocument Spreadsheet. This function uses box/spout to write the OpenDocument Spreadsheet file.
This saves me time in the future. When the database structure changes also the documentation changes, automatically. I could even send an email with an updated spreadsheet attached during the deployment process. The only thing I have to do is to keep the annotations in my entity files up-to-date. This does not require much time or effort. It’s not as much effort as manual adapting a separate documentation file every single time when touching the database structure. This would be just too much effort.
Next time I want to do something manually, I first need to ask myself, can I also automate it?
