3 * Analyses parsing data.
\r
6 * - update brother/sister
\r
7 * - update access/return
\r
9 * - inherit information
\r
11 * @version $Id: PhpdocAnalyser.php,v 1.5 2000/12/03 22:37:36 uw Exp $
\r
13 class PhpdocAnalyser extends PhpdocObject {
\r
16 * Flag indicating that getModule/getClass was called.
\r
20 var $flag_get = false;
\r
23 * List of all elements of a certain class/module.
\r
25 * The array is used to look up see references
\r
27 * @var array Format: elementlist[ eltype ][ elname ] = true
\r
28 * @see buildElementlist()
\r
30 var $elementlist = array();
\r
33 * Adds a suffix to the number like 1st, 2nd and 3th
\r
35 * @param integer $nr number to format
\r
37 * @author Thomas Weinert <subjective@subjective.de>
\r
39 function addNumberSuffix($nr) {
\r
41 $last_nr = substr($nr, -1, 1);
\r
56 } // end func addNumberSuffix
\r
59 * Starts the analysing of the raw parsing data.
\r
64 function analyse() {
\r
66 } // end func analyse
\r
69 * Handles brother and sister.
\r
72 * @see updateBrotherSisterElements()
\r
74 function updateBrothersSisters() {
\r
76 } // end func updateBrothersSisters
\r
79 * Updates certain elements that use brother and sister.
\r
81 * @return boolean $ok
\r
83 function updateBrotherSisterElements() {
\r
85 } // end func updateBrotherSisterElements
\r
88 * Copies fields from a brother or sister to the current element.
\r
90 * @param array Data of the target element that has a brother/sister tag
\r
91 * @param array Data of the element that is referenced by brother/sister
\r
93 function copyBrotherSisterFields($target, $from) {
\r
96 while (list($k, $v) = each($from))
\r
97 if (!isset($target[$k]) || "" == $target[$k])
\r
101 } // end func copyBrotherSisterFields
\r
104 * Updates the access and return tag values.
\r
106 * @see updateAccessReturnElements(), updateAccessElements()
\r
109 function updateAccessReturn() {
\r
111 } // end func updateAccessReturn
\r
114 * Updates access and return for certain elements.
\r
116 * This function should only be used to update functions.
\r
117 * Functions that have the same name as the class (constructors)
\r
118 * get return void and access public. Functions without
\r
119 * access get access public and functions without return get return void.
\r
121 * @return boolean $ok
\r
122 * @see updateAccessReturn()
\r
125 function updateAccessReturnElements() {
\r
127 } // end func updateAccessReturnElements
\r
130 * Updates access tags.
\r
132 * @see updateAccessReturnElements()
\r
135 function updateAccessElements() {
\r
137 } // end func updateAccessElements
\r
140 * Compares the param tags with the function head found.
\r
144 function checkFunctionArgs() {
\r
146 } // end func checkFunctionArgs
\r
149 * Looks for undocumented elements and adds a warning if neccessary.
\r
153 function findUndocumented() {
\r
155 } // end func findUndocumented
\r
158 * Checks all see references in the given classes/modulegroup.
\r
162 function checkSee() {
\r
164 } // end func checkSee
\r
167 * Checks see references in the given elementlist.
\r
171 function checkSeeElement() {
\r
173 } // end func checkSeeElement
\r
176 * Build a list of all elemente (functions, variables,...) of a certain class/module
\r
179 * @see $elementlist
\r
181 function buildElementlist() {
\r
183 } // end func buildElementlist
\r
186 * Compares the argument list generated from the function head with the param tags found.
\r
188 * PHPDoc is able to recognize these documentation mistakes:
\r
189 * - too few or too many param tags
\r
190 * - name does not match or is missing
\r
191 * - type does not match or is missing
\r
192 * - trouble with inherited elements
\r
194 * @param array Function arguments found by the parser
\r
195 * @param array Paramarray
\r
196 * @param string Functionname
\r
197 * @param string Filename
\r
198 * @param boolean Param tags inherited?
\r
199 * @return array $params Param array
\r
201 function checkArgDocs($args, $params, $elname, $elfile, $inherited = false) {
\r
203 // "param" contains the information from the @param tags.
\r
204 $num_args = count($args);
\r
205 $num_params = count($params);
\r
207 // no args? return...
\r
208 if (0 == $num_args && 0 == $num_params)
\r
211 // no args but @param used
\r
212 if (0 == $num_args && $num_params > 0) {
\r
216 $msg = "Function head shows no parameters, remove all @param tags.";
\r
217 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");
\r
221 if ("void" != $params[0]["type"]) {
\r
223 $msg = "The function inherited some parameter documentation from it's parentclass but PHPDoc could not find
\r
224 arguments in the function head. Add @param void to the doc comment to avoid confusion.";
\r
225 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");
\r
235 // compare the informations from the parser with the @param tags
\r
237 while (list($k, $arg) = each($args)) {
\r
239 if (isset($params[$k])) {
\r
241 if ($arg["optional"])
\r
242 $params[$k]["default"] = $arg["default"];
\r
246 if ("" != $arg["type"] && "" != $params[$k]["type"] && "mixed" != $params[$k]["type"] && strtolower($arg["type"]) != strtolower($params[$k]["type"])) {
\r
248 $type = $arg["type"];
\r
249 $msg = sprintf("%s parameter type '%s' does match the the documented type '%s', possible error consider an update to '@param %s %s %s' or '@param %s %s', the variable name is optional.",
\r
250 $this->addNumberSuffix($k + 1),
\r
252 $params[$k]["type"],
\r
255 (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)",
\r
257 (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)"
\r
260 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");
\r
262 } else if ("" != $params[$k]["type"]) {
\r
264 $type = $params[$k]["type"];
\r
268 $msg = sprintf('Type missing for the %s parameter, "mixed" assumed.', $this->addNumberSuffix($k));
\r
269 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "missing");
\r
274 $params[$k]["type"] = $type;
\r
278 if ("" != $params[$k]["type"] && strtolower($arg["type"]) != strtolower($params[$k]["type"])) {
\r
280 $type = (""!=$args["type"]) ? $arg["type"] : $params[$k]["type"];
\r
281 $msg = sprintf("Possible documentation error due to inherited information.
\r
282 The type of the %s parameter '%s' does not match the documented type '%s'.
\r
283 Override the inherited documentation if neccessary.",
\r
284 $this->addNumberSuffix($k),
\r
286 $params[$k]["type"]
\r
288 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");
\r
290 } else if ("" != $params[$k]["type"]) {
\r
292 $type = $params[$k]["type"];
\r
297 $msg = sprintf('Type missing for the %d parameter, "mixed" assumed. Override the inherited documentation if neccessary.', $k);
\r
298 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");
\r
302 $params[$k]["type"] = $type;
\r
306 if ("" != $params[$k]["name"] && $arg["name"] != $params[$k]["name"]) {
\r
308 $msg = sprintf("%s parameter '%s' does not match the documented name '%s', update the tag to '@param %s %s %s' or '@param %s %s', the variable name is optional.",
\r
309 $this->addNumberSuffix($k+1),
\r
311 $params[$k]["name"],
\r
314 (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)",
\r
316 (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)"
\r
319 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");
\r
320 $params[$k]["name"] = $arg["name"];
\r
322 } else if ("" == $params[$k]["name"]) {
\r
324 $params[$k]["name"] = $arg["name"];
\r
330 $msg = sprintf("%s parameter '%s' is not documented add '@param %s [description]' to the end of the @param[eter] list.",
\r
331 $this->addNumberSuffix($k+1),
\r
333 ("" == $arg["type"]) ? "(object objectname|type)" : $arg["type"]
\r
336 $params[$k]["name"] = $arg["name"];
\r
337 $params[$k]["undoc"] = true;
\r
339 if ("" != $arg["type"])
\r
340 $params[$k]["type"] = $arg["type"];
\r
342 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "missing");
\r
347 // more @params specified than variables where found in the function head, delete them
\r
348 if ($num_params > $num_args) {
\r
350 $msg = "The parser found '$num_args' parameter but '$num_params' @param[eter] tags. You should update the @param[eter] list.";
\r
351 $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");
\r
352 for ($i = $k + 1; $i < $num_params; ++$i)
\r
353 unset($params[$i]);
\r
358 } // end func checkArgDocs
\r
360 } // end func PhpdocAnalyser
\r