+++ /dev/null
-################################################################################\r
- phpDocumentor Frequently Asked Questions\r
-\r
-################################################################################\r
-Introduction\r
-################################################################################\r
-\r
-Before we start with questions and their answers, make sure to read the\r
-documentation *thoroughly* found at http://www.phpdoc.org/manual.php. The\r
-complexity of phpDocumentor can be a bit impenetrable until you understand the\r
-logic behind it.\r
-\r
-If you have read the documentation thoroughly, and have read this FAQ and you\r
-are still lost, please go directly to the bug database at\r
-http://sourceforge.net/tracker/?group_id=11194&atid=111194 and read through the\r
-open bugs. If you don't find the solution to your problem (or proof that it\r
-at least is not your fault), then go to the help forum and post a help message\r
-at http://sourceforge.net/forum/forum.php?forum_id=35065.\r
-\r
-################################################################################\r
-All Questions (Table of Contents)\r
-################################################################################\r
-Installation\r
- Q: There is no package.xml in the release, where is it?\r
-Documentation Errors\r
- Q: I keep getting an illegal package tag error for the first DocBlock in a file,\r
- isn't this a page-level DocBlock?\r
- Q: I keep getting a warning that there is no @package tag in file xxx.php, but\r
- there is a @package tag in the class definition, doesn't this apply to the\r
- file?\r
-Feature Requests\r
- Q: Can you implement the @example tag inline so that I can put PHP source code\r
- examples directly in DocBlocks?\r
-Crash/Segfaults\r
- Q: phpDocumentor crashes if I use __FUNCTION__!!!\r
- \r
-################################################################################\r
-Installation\r
-################################################################################\r
-\r
-Q: There is no package.xml in the release, where is it?\r
-\r
-A: this problem occurs when one does the faulty steps of:\r
-\r
-$ tar xvf PhpDocumentor-1.3.1.tgz\r
-$ pear install package.xml\r
-\r
- instead, the user should simply run:\r
-\r
-$ pear install PhpDocumentor-1.3.1.tgz\r
-\r
- or, if the zlib extension is not enabled:\r
-\r
-$ gunzip PhpDocumentor-1.3.1.tgz\r
-$ pear install PhpDocumentor-1.3.1.tar\r
-\r
-################################################################################\r
-Documentation Errors\r
-################################################################################\r
-\r
-Q: I keep getting an illegal package tag error for the first DocBlock in a file,\r
- isn't this a page-level DocBlock?\r
-\r
----\r
----[[UPDATE]]\r
----VERSION 1.2.2 has a different page-level docblock recognition algorithm\r
----Now, the first docblock in a file is a page-level docblock if it contains\r
----a @package tag.\r
----\r
-A: Please read the documentation very carefully. A page-level DocBlock does\r
- occur at the start of a file, but the first DocBlock is not always a\r
- page-level DocBlock! Why is this? Very often, you will want to document\r
- the entire page, or describe it (this page contains functions for blah), and\r
- also document the first item in a page separately. An example:\r
- \r
- <?php\r
- /**\r
- * This file contains all foobar functions and defines\r
- * @package mypackage\r
- */\r
- /**\r
- * controls parsing of bar information\r
- */\r
- define('parse_bar',true);\r
- ?>\r
- \r
- The page has its own information, and the define has its own information.\r
- An example of what not to do:\r
- \r
- <?php\r
- /**\r
- * This file contains all foobar functions and defines\r
- * @package mypackage\r
- */\r
- define('parse_bar',true);\r
- ?>\r
- \r
- Here, the DocBlock belongs to the define and not to the page! phpDocumentor\r
- can successfully parse this DocBlock, but it will apply the comment to the\r
- documentation of define('parse_bar',true); and not to the page. Therefore,\r
- it warns you that your @package tag will be ignored because defines may not\r
- contain a @package tag.\r
-\r
-Q: I keep getting a warning that there is no @package tag in file xxx.php, but\r
- there is a @package tag in the class definition, doesn't this apply to the\r
- file?\r
-\r
-A: No. This example does not have a page-level DocBlock:\r
-\r
- <?php\r
- /**\r
- * This class is in package mypackage\r
- * @package mypackage\r
- */\r
- class in_mypackage {...}\r
- ?>\r
- \r
- phpDocumentor therefore assumes the page-level package is the same as the\r
- class package, mypackage. This is fine in most cases, but if multiple\r
- classes are in the same file with different packages, as in:\r
-\r
- <?php\r
- /**\r
- * This class is in package mypackage\r
- * @package mypackage\r
- */\r
- class in_mypackage {...}\r
- /**\r
- * This class is in package anotherpackage\r
- * @package anotherpackage\r
- */\r
- class in_anotherpackage {...}\r
- ?>\r
- \r
- There is no way to determine which package the page should belong to, and\r
- phpDocumentor will automatically put it in the default package. This can\r
- cause incredible headaches debugging, and so we have added a warning in the\r
- 1.2.0 series that informs you if the package is inferred by phpDocumentor.\r
- To fix this warning, simply place a page-level DocBlock with a @package tag\r
- like:\r
-\r
- <?php\r
- /**\r
- * This file contains two packages\r
- * @package filepackage\r
- */\r
- /**\r
- * This class is in package mypackage\r
- * @package mypackage\r
- */\r
- class in_mypackage {...}\r
- /**\r
- * This class is in package anotherpackage\r
- * @package anotherpackage\r
- */\r
- class in_anotherpackage {...}\r
- ?>\r
-################################################################################\r
-Feature Requests\r
-################################################################################\r
-Q: Can you implement the @example tag inline so that I can put PHP source code\r
- examples directly in DocBlocks?\r
-\r
-A: This is implemented using the HTML <code></code> tags as in:\r
-\r
- /**\r
- * Short description\r
- *\r
- * Start of long description, here is a code example:\r
- * <code>\r
- * $my_phpcode = "easy to explain";\r
- * </code>\r
- * More text\r
- * <code>\r
- * define('morecode',true);\r
- * </code>\r
- */\r
-################################################################################\r
-Crash/Segfaults\r
-################################################################################\r
-Q: phpDocumentor crashes if I use __FUNCTION__!!!\r
-\r
-A: This is caused by a known bug in all PHP versions prior to 4.3.2. It was\r
- fixed in PHP 4.3.2RC1, you must upgrade to PHP 4.3.2 if you use __FUNCTION__\r
- in code that you wish to document (sorry!) or apply the bugfix patch to the\r
- tokenizer extension and recompile php (see the php.internals archive at\r
- php.net for help)\r
projects / atutor.git / blobdiff