Ever since I discovered phpDocumentor I have been fascinated by the idea of automatic Documentation Generation. Especially for large projects where an in-depth understanding of the code is a requirement.
Unfortunately, the more I got to work with phpDocumentor the more issues surfaced with its performance, ease of use and above all: memory usage.
Over time I have encountered at least 1 project which could not be processed by phpDocumentor. This was unfortunate and thus I decided to try and contribute to the phpDocumentor project. After a pleasant introduction and solving a minor bug I attempted to solve, or at least decrease, the memory usage issues which were the main cause of my dissatisfaction.
Long story short: I gave up.
Although the application can work magic for some projects, I was unable to adapt the code base (which is reasonable old). The memory issues seemed to be partly due to the architecture of the application and the choices in the past. To change this would mean a rather large refactoring of the application.
Right before or during the Dutch PHP Conference 2010 the issue had arisen again and this time I was determined on solving it. In the end I chose to build a new Documentation Generation Application (may I coin DGA?) for PHP for which I had the following spear points in mind:
- Execution duration had to be as short as possible.
- Memory usage should at all times be within an acceptable range (less than 100mb).
- Focus on assisting Continuous Integration.
- Compatible with the latest PHP versions.
- Compatible with the basic phpDocumentor CLI arguments.
- Aid the user with Ajax enabled search and more.
With these requirements written down in a small TODO file I started designing the new project (which at the time was still nameless).
After spending some hours designing, coding, prototyping, designing, coding and testing is now the time to reveal the fruits of my labour: DocBlox
Currently DocBlox is still in an pre-release state (version 0.7.1) but is well underway to version 1.0. Even though I have marked this version as being pre-release, it is fully capable of parsing your source code and creating static HTML pages (PDF support is planned for the near future).
DocBlox sports many features which help you reading the documentation hidden in your source code. Please take a look at https://github.com/mvriel/Docblox/wiki/Features for an overview!
Conclusion and where to get it
DocBlox is a new, versatile Documentation Generation Application (DGA) which enables large and / or PHP 5.3 projects to generate their documentation. It is compatible with many of the features that you are used to in other DGA’s.
You can get the source files from GitHub at: https://github.com/mvriel/Docblox
Some documentation is also available at Github; but most is still under development. You can check the README, TODO and CHANGELOG in the project to see how to use the application and what is on the roadmap.
Try it and I hope you like it.
Either way, thank you and let me know!