Writing Self-Documenting PHP Code (
Page 1 of 7 )
Are you the kind of person who hates documenting your source
code? Does the thought of writing API documentation make your eyeballs
contract and your toes itch? Well, itch no more - this article
demonstrates how you can use PHPDoc to automatically generate API
documentation using the comments in your source code.There are two things that developers hate.
Fixing bugs. And writing
documentation.
Now, while the first can be handled through better
planning and execution, it's the second one that really gets a developer's goat.
Most developers can't stand the thought of documenting their own code, finding
it both tedious and a waste of their time and skills (although, strangely
enough, they're the first to complain about the "lack of documentation" when it
comes to someone else's code.)
The fact of the matter, though, is that
you're fooling yourself if you think that you can survive without documentation.
Properly-documented application code makes it easier to trace and squash bugs,
to maintain code over the long run, and to improve both the productivity of the
programmer and the quality of the software. You can't avoid it, and so you're
just going to have to grow up and learn to live with it.
And that's
where this article comes in. Over the next few pages, I'm going to introduce you
to PHPDoc, a documentation system for PHP that relies on comments within your
code to automatically generate documentation for your PHP classes. As you will
see, using PHPDoc can simplify the task of creating API documentation and
thereby save you a significant amount of time in the post-release phase of a
software project.
/ 14 
