Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

executable file 187 lines (158 sloc) 6.668 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
################################################################################
phpDocumentor Frequently Asked Questions

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

Before we start with questions and their answers, make sure to read the
documentation *thoroughly* found at http://www.phpdoc.org/manual.php. The
complexity of phpDocumentor can be 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.

################################################################################
All Questions (Table of Contents)
################################################################################
Installation
Q: There is no package.xml in the release, where is it?
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?
 Q: I keep getting a warning that there is no @package tag in file xxx.php, but
    there is a @package tag in the class definition, doesn't this apply to the
file?
Feature Requests
Q: Can you implement the @example tag inline so that I can put PHP source code
examples directly in DocBlocks?
Crash/Segfaults
Q: phpDocumentor crashes if I use __FUNCTION__!!!
################################################################################
Installation
################################################################################

Q: There is no package.xml in the release, where is it?

A: this problem occurs when one does the faulty steps of:

$ tar xvf PhpDocumentor-1.3.1.tgz
$ pear install package.xml

instead, the user should simply run:

$ pear install PhpDocumentor-1.3.1.tgz

or, if the zlib extension is not enabled:

$ gunzip PhpDocumentor-1.3.1.tgz
$ pear install PhpDocumentor-1.3.1.tar

################################################################################
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?

---
---[[UPDATE]]
---VERSION 1.2.2 has a different page-level docblock recognition algorithm
---Now, the first docblock in a file is a page-level docblock if it contains
---a @package tag.
---
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.

Q: I keep getting a warning that there is no @package tag in file xxx.php, but
   there is a @package tag in the class definition, doesn't this apply to the
file?

A: No. This example does not have a page-level DocBlock:

<?php
/**
* This class is in package mypackage
* @package mypackage
*/
class in_mypackage {...}
?>
phpDocumentor therefore assumes the page-level package is the same as the
class package, mypackage. This is fine in most cases, but if multiple
classes are in the same file with different packages, as in:

<?php
/**
* This class is in package mypackage
* @package mypackage
*/
class in_mypackage {...}
/**
* This class is in package anotherpackage
* @package anotherpackage
*/
class in_anotherpackage {...}
?>
There is no way to determine which package the page should belong to, and
phpDocumentor will automatically put it in the default package. This can
cause incredible headaches debugging, and so we have added a warning in the
1.2.0 series that informs you if the package is inferred by phpDocumentor.
To fix this warning, simply place a page-level DocBlock with a @package tag
like:

<?php
/**
* This file contains two packages
* @package filepackage
*/
/**
* This class is in package mypackage
* @package mypackage
*/
class in_mypackage {...}
/**
* This class is in package anotherpackage
* @package anotherpackage
*/
class in_anotherpackage {...}
?>
################################################################################
Feature Requests
################################################################################
Q: Can you implement the @example tag inline so that I can put PHP source code
examples directly in DocBlocks?

A: This is implemented using the HTML <code></code> tags as in:

/**
* Short description
*
* Start of long description, here is a code example:
* <code>
* $my_phpcode = "easy to explain";
* </code>
* More text
* <code>
* define('morecode',true);
    * </code>
    */
################################################################################
Crash/Segfaults
################################################################################
Q: phpDocumentor crashes if I use __FUNCTION__!!!

A: This is caused by a known bug in all PHP versions prior to 4.3.2. It was
   fixed in PHP 4.3.2RC1, you must upgrade to PHP 4.3.2 if you use __FUNCTION__
   in code that you wish to document (sorry!) or apply the bugfix patch to the
   tokenizer extension and recompile php (see the php.internals archive at
   php.net for help)
Something went wrong with that request. Please try again.