Documenting External Dependancies

There is an issue which kind of bugged me with external dependencies in my source code documentation after it is parsed by phpDocumentor, the source code doc does not know much about the external libraries, and therefore leaves references to them dangling…

This particular problem is highlighted when you use the source code highlighting feature (BTW: very cool feature!!!) and have a class method which returns an external class. Where you can normally click on the return class and jump to it’s documentation in your source code, you are only told the name of the class when it is external to the project.

This is rightfully so, after all “You don’t know what you don’t know.” You can not expect phpDocumentor to know about your external dependencies in a vacuum. What I have come up with in my own experimentation is to stub in a small file in the project called external.php which documents the classes as a 50,000 ft. level, and provides a link to the source of the external library. Obviously, you do not want to include this file in you project, as it would cause class re-definitions and all sorts of problems, but as a stop gap for documentation, it seems to work well.

external.php:

<?php

< ?php
/**
 *    Identify external dependancies for library classes
 *    for purposes of phpDocumentor inclusion
 *
 *    !!!WARNING! WARNING! WARNING!!!
 *            Do not include this file in the project code.
 *            It will cause the application to break. This file
 *            is for documentation only.
 *    !!!WARNING! WARNING! WARNING!!!
 *
 *    @author        Jason E. Sweat
 *    @since        2004-11-20
 *    @version    $Id: external.php,v 1.3 2004/11/22 16:03:35 sweatje Exp $
 *    @package    YourProject
 *    @subpackage    external
 */

/**#@+
 * SimpleTest 
 * @link http://simpletest.sf.net/
 */
class UnitTestCase {}
class WebTestCase {}
/**#@-*/

/**#@+
 * WACT
 * Web Application Component Toolkit
 * @link http://wact.sf.net/
 */
class WACT {}
class FormView {}
class ArrayDataSet extends WACT {}
class DataSpace extends WACT {}
class DatasetDecorator extends WACT {}
/**#@-*/

/**#@+
 * SPL
 * Standard PHP Library
 * @link http://www.php.net/~helly/php/ext/spl/
 */
class Exception {}
/**#@-*/

?>

This "fix" seems to clean up the class tree significantly where you have extended classes from external libraries as well.