Detailed Documentation of the tag specification are available with this distribution in the specs/ directory, and online at http://phpdocu.sourceforge.net/spec/
A brief howto tutorial is available in specs/howto.html and online at http://phpdocu.sourceforge.net/spec/howto.html
If you think you've found a bug in phpDocumentor, please check our bug tracker online at http://sourceforge.net/tracker/?func=browse&group_id=11194&atid=111194, the bug may have already been fixed (we develop at a rapid rate). If you don't find it, please submit a bug, and we will attempt to fix it as quickly as possible.
If there is a feature you're dying to have, check our feature tracker at http://sourceforge.net/tracker/?func=browse&group_id=11194&atid=361194. Please don't hesitate to look right at the source code and help apply your feature. We love that, and can easily give you access to the cvs.
If you would like to help out with phpDocumentor, don't be shy. Email Joshua Eichorn right away and say you'd like to be added to the developer team. We need people who are willing to develop Converters, translate documentation, and handle various bugs and feature requests as they come up. phpDocumentor is fast becoming the de facto standard of automatic documentors in PHP, so it is in your best interest to make sure it works the way you need it to work.
There are two ways of using phpDocumentor, the command-line tool phpdoc, or the web interface {@link phpdoc.php}.
phpDocumentor works by reading command-line options via an {@link Io} object, and then passing these options to {@link Parser::parse()}. The parser is an event-driven parser that parses php files into abstract data structures defined in {@link ParserData.inc}, and passes them through {@link Publisher::publishEvent()} to {@link IntermediateParser::handleEvent()}. This method then passes the abstract {@link parserElement} descendant or {@link parserDocBlock} to a handleElement function (one of {@link IntermediateParser::handleDocBlock(), IntermediateParser::handleClass(), IntermediateParser::handleInclude(), IntermediateParser::handleFunction(), IntermediateParser::handleMethod(), IntermediateParser::handleVar(), IntermediateParser::handleDefine()} or {@link IntermediateParser::handlePage()}.
These functions split the elements up by their type. There are 2 types of elements, Procedural and Object-oriented. Procedural elements are functions, defines, includes, and global variables, and Object-oriented elements are classes, methods, and vars. Procedural elements are handled by {@link ProceduralPages}. Classes are handled by another class, {@link Classes}, which organizes inheritance.
Both the ProceduralPages and Classes class organizes classes and their methods and variables by the file that they are located in. After all parsing is complete, the code calls {@link IntermediateParser::fixClasses()} and {@link IntermediateParser::fixProcPages()} (both private methods), which in turn calls {@link Classes::Inherit()} and {@link ProceduralPages::setupPages()}. Inherit walks through the {@link Classes::$roots} array of classes that have no parents in their package, and sets up inheritance in child classes down the class inheritance tree. Then, fixClasses() sets the arrays that {@link Converter} will need to process the parsed data structures into template-ready data and handles intra-package and inter-package name conflicts (classes with the same name). setupPages handles inheriting page packages from the classes that are in the pages, and also handles intra-package and inter-package name conflicts among linkable procedural page elements (define, global variable, function).
The {@link Converters#Converter::walk()} method does the primary work of converting abstract parsed data into {@link Template}-enabled data. phpDocumentor 1.1 ships with the abstract Converter and a standard {@link Converters#HTMLdefaultConverter} for output to HTML formats as well as a pre-alpha PDF {@link Converters#PDFdefaultConverter}. The converter is described in detail in the Converter howto and the Converters Package-level documentation.
After conversion, Converter calls the {@link Converters#Converter::Output()} method for each converter, and voila, the data is written out!