How do I maintain high-level documentation along with phpdoc generated documentation?

Question

For my first open source project (shameless plug: mtChart) I currently have two different types of documentations:

• HTML files generated by Doxygen from the phpdoc-comments within the code
• The wiki pages on Google Code (Or simply put: Additional text files)

The Doxygen files are really great, but I miss the possiblity to add 'high-level' documentation: Tutorials, examples, overview over the system, roadmaps etc.

How do I combine these two in an automated manner so I can keep the code documentation updated with somehow automatically including the rest of the texts?

(I'm willing to move away from Doxygen if necessary.)

Answer 1

If you use phpdoc-style you're obviously aware that you could do the examples, tutorials etc right inside it and provide links to external content like roadmaps as necessary. It is not ideal but definitely works and gives you a consistent and useful documentation. Just use some formating inside your comments for easy-to read text and @see for the links. You might also consider using inline tags but I am not sure you need to go as far as that from the start.

/**
 * @todo Need to move to the main framework
 *
 *        class: RegistrationPeer extends AbstractPeer
 *      package: Registration
 *   subpackage: Peer
 *
 *       method: findByUserId($userId)
 *   visibility: public
 *       static: yes
 *
 *         file: xxx
 *
 *        class: Registration extends AbstractModel
 *      package: Registration
 *   subpackage: Model
 *
 * Sample usage:
 * <code>
 * <?php
 *     $userId = $sessionManager->getRegUid();
 *     $registration = RegistrationPeer::findByUserId($userId);
 * ?>
 * </code>
 *
 * @see AbstractPeer
 * @see http://docs.google.com/Doc?docid=xxxx&amp;hl=en
 *
 * @author xxx
 */