We use phpDocumentor, a tool for creating documentation directly from both PHP and external documentation, to keep track of all our code documentation. The documentation within the code is done using PHPDoc which is an adaptation of Javadoc for the PHP programming language.
The objective of documenting code is to makes it easier to understand and lower the barrier to entry for developers wishing to contribute to the codebase. It also facilitates painless maintenance (refactoring, bug fixes etc).
Basic Commenting
The first thing to take note of is that PHPDoc comments must be enclosed in DocBlocks. A DocBlock is a C-stlye comment that begins with a /** with a leading asterisk (*) on each line. Any line within a DocBlock that doesn't begin with a * will be ignored. Example:
Secondly, DocBlocks must precede the code you are adding comments to. For example, if you wanted to document the function foo(), you would proceed as follows: