mods/phpdoc2/PhpDocumentor/FAQ

   1 ################################################################################\r
   2                                 phpDocumentor Frequently Asked Questions\r
   3 \r
   4 ################################################################################\r
   5 Introduction\r
   6 ################################################################################\r
   7 \r
   8 Before we start with questions and their answers, make sure to read the\r
   9 documentation *thoroughly* found at http://www.phpdoc.org/manual.php.  The\r
  10 complexity of phpDocumentor can be a bit impenetrable until you understand the\r
  11 logic behind it.\r
  12 \r
  13 If you have read the documentation thoroughly, and have read this FAQ and you\r
  14 are still lost, please go directly to the bug database at\r
  15 http://sourceforge.net/tracker/?group_id=11194&atid=111194 and read through the\r
  16 open bugs.  If you don't find the solution to your problem (or proof that it\r
  17 at least is not your fault), then go to the help forum and post a help message\r
  18 at http://sourceforge.net/forum/forum.php?forum_id=35065.\r
  19 \r
  20 ################################################################################\r
  21 All Questions (Table of Contents)\r
  22 ################################################################################\r
  23 Installation\r
  24  Q: There is no package.xml in the release, where is it?\r
  25 Documentation Errors\r
  26  Q: I keep getting an illegal package tag error for the first DocBlock in a file,\r
  27     isn't this a page-level DocBlock?\r
  28  Q: I keep getting a warning that there is no @package tag in file xxx.php, but\r
  29     there is a @package tag in the class definition, doesn't this apply to the\r
  30     file?\r
  31 Feature Requests\r
  32  Q: Can you implement the @example tag inline so that I can put PHP source code\r
  33     examples directly in DocBlocks?\r
  34 Crash/Segfaults\r
  35  Q: phpDocumentor crashes if I use __FUNCTION__!!!\r
  36  \r
  37 ################################################################################\r
  38 Installation\r
  39 ################################################################################\r
  40 \r
  41 Q: There is no package.xml in the release, where is it?\r
  42 \r
  43 A: this problem occurs when one does the faulty steps of:\r
  44 \r
  45 $ tar xvf PhpDocumentor-1.3.1.tgz\r
  46 $ pear install package.xml\r
  47 \r
  48    instead, the user should simply run:\r
  49 \r
  50 $ pear install PhpDocumentor-1.3.1.tgz\r
  51 \r
  52    or, if the zlib extension is not enabled:\r
  53 \r
  54 $ gunzip PhpDocumentor-1.3.1.tgz\r
  55 $ pear install PhpDocumentor-1.3.1.tar\r
  56 \r
  57 ################################################################################\r
  58 Documentation Errors\r
  59 ################################################################################\r
  60 \r
  61 Q: I keep getting an illegal package tag error for the first DocBlock in a file,\r
  62    isn't this a page-level DocBlock?\r
  63 \r
  64 ---\r
  65 ---[[UPDATE]]\r
  66 ---VERSION 1.2.2 has a different page-level docblock recognition algorithm\r
  67 ---Now, the first docblock in a file is a page-level docblock if it contains\r
  68 ---a @package tag.\r
  69 ---\r
  70 A: Please read the documentation very carefully.  A page-level DocBlock does\r
  71    occur at the start of a file, but the first DocBlock is not always a\r
  72    page-level DocBlock!  Why is this?  Very often, you will want to document\r
  73    the entire page, or describe it (this page contains functions for blah), and\r
  74    also document the first item in a page separately.  An example:\r
  75    \r
  76    <?php\r
  77    /**\r
  78    * This file contains all foobar functions and defines\r
  79    * @package mypackage\r
  80    */\r
  81    /**\r
  82    * controls parsing of bar information\r
  83    */\r
  84    define('parse_bar',true);\r
  85    ?>\r
  86    \r
  87    The page has its own information, and the define has its own information.\r
  88    An example of what not to do:\r
  89    \r
  90    <?php\r
  91    /**\r
  92    * This file contains all foobar functions and defines\r
  93    * @package mypackage\r
  94    */\r
  95    define('parse_bar',true);\r
  96    ?>\r
  97    \r
  98    Here, the DocBlock belongs to the define and not to the page!  phpDocumentor\r
  99    can successfully parse this DocBlock, but it will apply the comment to the\r
 100    documentation of define('parse_bar',true); and not to the page.  Therefore,\r
 101    it warns you that your @package tag will be ignored because defines may not\r
 102    contain a @package tag.\r
 103 \r
 104 Q: I keep getting a warning that there is no @package tag in file xxx.php, but\r
 105    there is a @package tag in the class definition, doesn't this apply to the\r
 106    file?\r
 107 \r
 108 A: No.  This example does not have a page-level DocBlock:\r
 109 \r
 110    <?php\r
 111    /**\r
 112    * This class is in package mypackage\r
 113    * @package mypackage\r
 114    */\r
 115    class in_mypackage {...}\r
 116    ?>\r
 117    \r
 118    phpDocumentor therefore assumes the page-level package is the same as the\r
 119    class package, mypackage.  This is fine in most cases, but if multiple\r
 120    classes are in the same file with different packages, as in:\r
 121 \r
 122    <?php\r
 123    /**\r
 124    * This class is in package mypackage\r
 125    * @package mypackage\r
 126    */\r
 127    class in_mypackage {...}\r
 128    /**\r
 129    * This class is in package anotherpackage\r
 130    * @package anotherpackage\r
 131    */\r
 132    class in_anotherpackage {...}\r
 133    ?>\r
 134    \r
 135    There is no way to determine which package the page should belong to, and\r
 136    phpDocumentor will automatically put it in the default package.  This can\r
 137    cause incredible headaches debugging, and so we have added a warning in the\r
 138    1.2.0 series that informs you if the package is inferred by phpDocumentor.\r
 139    To fix this warning, simply place a page-level DocBlock with a @package tag\r
 140    like:\r
 141 \r
 142    <?php\r
 143    /**\r
 144    * This file contains two packages\r
 145    * @package filepackage\r
 146    */\r
 147    /**\r
 148    * This class is in package mypackage\r
 149    * @package mypackage\r
 150    */\r
 151    class in_mypackage {...}\r
 152    /**\r
 153    * This class is in package anotherpackage\r
 154    * @package anotherpackage\r
 155    */\r
 156    class in_anotherpackage {...}\r
 157    ?>\r
 158 ################################################################################\r
 159 Feature Requests\r
 160 ################################################################################\r
 161 Q: Can you implement the @example tag inline so that I can put PHP source code\r
 162    examples directly in DocBlocks?\r
 163 \r
 164 A: This is implemented using the HTML <code></code> tags as in:\r
 165 \r
 166    /**\r
 167     * Short description\r
 168     *\r
 169     * Start of long description, here is a code example:\r
 170     * <code>\r
 171     *  $my_phpcode = "easy to explain";\r
 172     * </code>\r
 173     * More text\r
 174     * <code>\r
 175     *  define('morecode',true);\r
 176     * </code>\r
 177     */\r
 178 ################################################################################\r
 179 Crash/Segfaults\r
 180 ################################################################################\r
 181 Q: phpDocumentor crashes if I use __FUNCTION__!!!\r
 182 \r
 183 A: This is caused by a known bug in all PHP versions prior to 4.3.2.  It was\r
 184    fixed in PHP 4.3.2RC1, you must upgrade to PHP 4.3.2 if you use __FUNCTION__\r
 185    in code that you wish to document (sorry!) or apply the bugfix patch to the\r
 186    tokenizer extension and recompile php (see the php.internals archive at\r
 187    php.net for help)\r