################################################################################
				phpDocumentor Frequently Asked Questions

################################################################################
Introduction
################################################################################

Before we start with questions and their answers, make sure to read the
documentation *thoroughly* found in the spec/ subdirectory.  The complexity of
phpDocumentor is a bit impenetrable until you understand the logic behind it.

If you have read the documentation thoroughly, and have read this FAQ and you
are still lost, please go directly to the bug database at
http://sourceforge.net/tracker/?group_id=11194&atid=111194 and read through the
open bugs.  If you don't find the solution to your problem (or proof that it
at least is not your fault), then go to the help forum and post a help message
at http://sourceforge.net/forum/forum.php?forum_id=35065.

################################################################################
Installation
################################################################################

Q: [UNIX ONLY] When I run phpdoc from outside its directory, it doesn't work!

A: This is a two-fold problem.  First, you must make sure the first line of
   phpdoc points to the path to PHP.  It defaults to:
   
   #!/usr/local/bin/php -q

   Change this to the correct path.  If this does not fix your problem, then you
   must make sure that php's include_path ini setting refers either to the
   directory that phpDocumentor is in, or to the PEAR directory if and ONLY if
   you installed phpDocumentor from PEAR.  If this doesn't fix your problem
   post a message at the sourceforge help forum.
   
################################################################################
Documentation Errors
################################################################################

Q: I keep getting an illegal package tag error for the first DocBlock in a file,
   isn't this a page-level DocBlock?

A: Please read the documentation very carefully.  A page-level DocBlock does
   occur at the start of a file, but the first DocBlock is not always a
   page-level DocBlock!  Why is this?  Very often, you will want to document
   the entire page, or describe it (this page contains functions for blah), and
   also document the first item in a page separately.  An example:
   
   <?php
   /**
   * This file contains all foobar functions and defines
   * @package mypackage
   */
   /**
   * controls parsing of bar information
   */
   define('parse_bar',true);
   ?>
   
   The page has its own information, and the define has its own information.
   An example of what not to do:
   
   <?php
   /**
   * This file contains all foobar functions and defines
   * @package mypackage
   */
   define('parse_bar',true);
   ?>
   
   Here, the DocBlock belongs to the define and not to the page!  phpDocumentor
   can successfully parse this DocBlock, but it will apply the comment to the
   documentation of define('parse_bar',true); and not to the page.  Therefore,
   it warns you that your @package tag will be ignored because defines may not
   contain a @package tag.
