+++ /dev/null
-<?php\r
-/**\r
-* Analyses parsing data.\r
-*\r
-* Analyse means:\r
-* - update brother/sister\r
-* - update access/return\r
-* - inherit elements\r
-* - inherit information\r
-*\r
-* @version $Id: PhpdocAnalyser.php,v 1.5 2000/12/03 22:37:36 uw Exp $\r
-*/\r
-class PhpdocAnalyser extends PhpdocObject {\r
-\r
- /**\r
- * Flag indicating that getModule/getClass was called.\r
- *\r
- * @var boolean\r
- */\r
- var $flag_get = false;\r
- \r
- /**\r
- * List of all elements of a certain class/module.\r
- *\r
- * The array is used to look up see references\r
- * \r
- * @var array Format: elementlist[ eltype ][ elname ] = true\r
- * @see buildElementlist()\r
- */\r
- var $elementlist = array();\r
- \r
- /**\r
- * Adds a suffix to the number like 1st, 2nd and 3th\r
- *\r
- * @param integer $nr number to format\r
- * @return string\r
- * @author Thomas Weinert <subjective@subjective.de>\r
- */\r
- function addNumberSuffix($nr) {\r
- \r
- $last_nr = substr($nr, -1, 1);\r
-\r
- switch ($last_nr) {\r
- case 1: \r
- return ($nr."st"); \r
- break;\r
-\r
- case 2:\r
- return ($nr."nd"); \r
- break;\r
-\r
- default: \r
- return ($nr."th");\r
- }\r
-\r
- } // end func addNumberSuffix\r
-\r
- /**\r
- * Starts the analysing of the raw parsing data.\r
- *\r
- * @access public\r
- * @abstract\r
- */\r
- function analyse() {\r
- ;\r
- } // end func analyse\r
-\r
- /**\r
- * Handles brother and sister.\r
- *\r
- * @abstract\r
- * @see updateBrotherSisterElements()\r
- */\r
- function updateBrothersSisters() {\r
- ;\r
- } // end func updateBrothersSisters\r
-\r
- /**\r
- * Updates certain elements that use brother and sister.\r
- *\r
- * @return boolean $ok\r
- */\r
- function updateBrotherSisterElements() {\r
- return false;\r
- } // end func updateBrotherSisterElements\r
- \r
- /**\r
- * Copies fields from a brother or sister to the current element.\r
- * \r
- * @param array Data of the target element that has a brother/sister tag\r
- * @param array Data of the element that is referenced by brother/sister\r
- */\r
- function copyBrotherSisterFields($target, $from) {\r
- \r
- reset($from);\r
- while (list($k, $v) = each($from)) \r
- if (!isset($target[$k]) || "" == $target[$k]) \r
- $target[$k] = $v;\r
- \r
- return $target;\r
- } // end func copyBrotherSisterFields\r
-\r
- /**\r
- * Updates the access and return tag values.\r
- *\r
- * @see updateAccessReturnElements(), updateAccessElements()\r
- * @abstract\r
- */\r
- function updateAccessReturn() {\r
- ;\r
- } // end func updateAccessReturn\r
-\r
- /**\r
- * Updates access and return for certain elements.\r
- *\r
- * This function should only be used to update functions.\r
- * Functions that have the same name as the class (constructors)\r
- * get return void and access public. Functions without\r
- * access get access public and functions without return get return void.\r
- *\r
- * @return boolean $ok\r
- * @see updateAccessReturn()\r
- * @abstract\r
- */\r
- function updateAccessReturnElements() {\r
- ;\r
- } // end func updateAccessReturnElements\r
-\r
- /**\r
- * Updates access tags.\r
- *\r
- * @see updateAccessReturnElements()\r
- * @abstract\r
- */\r
- function updateAccessElements() {\r
- ;\r
- } // end func updateAccessElements\r
-\r
- /**\r
- * Compares the param tags with the function head found.\r
- *\r
- * @abstract\r
- */\r
- function checkFunctionArgs() {\r
- ;\r
- } // end func checkFunctionArgs\r
-\r
- /**\r
- * Looks for undocumented elements and adds a warning if neccessary.\r
- *\r
- * @abstract\r
- */\r
- function findUndocumented() {\r
- ;\r
- } // end func findUndocumented\r
- \r
- /**\r
- * Checks all see references in the given classes/modulegroup.\r
- * \r
- * @abstract\r
- */\r
- function checkSee() {\r
- ; \r
- } // end func checkSee\r
- \r
- /**\r
- * Checks see references in the given elementlist.\r
- * \r
- * @abstract\r
- */\r
- function checkSeeElement() {\r
- ;\r
- } // end func checkSeeElement\r
- \r
- /**\r
- * Build a list of all elemente (functions, variables,...) of a certain class/module\r
- * \r
- * @abstract\r
- * @see $elementlist\r
- */\r
- function buildElementlist() {\r
- ; \r
- } // end func buildElementlist\r
-\r
- /**\r
- * Compares the argument list generated from the function head with the param tags found.\r
- *\r
- * PHPDoc is able to recognize these documentation mistakes:\r
- * - too few or too many param tags\r
- * - name does not match or is missing\r
- * - type does not match or is missing\r
- * - trouble with inherited elements\r
- *\r
- * @param array Function arguments found by the parser\r
- * @param array Paramarray\r
- * @param string Functionname\r
- * @param string Filename\r
- * @param boolean Param tags inherited?\r
- * @return array $params Param array\r
- */\r
- function checkArgDocs($args, $params, $elname, $elfile, $inherited = false) {\r
- \r
- // "param" contains the information from the @param tags.\r
- $num_args = count($args);\r
- $num_params = count($params);\r
-\r
- // no args? return...\r
- if (0 == $num_args && 0 == $num_params)\r
- return array();\r
-\r
- // no args but @param used\r
- if (0 == $num_args && $num_params > 0) {\r
- \r
- if (!$inherited) {\r
- \r
- $msg = "Function head shows no parameters, remove all @param tags.";\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");\r
-\r
- } else {\r
-\r
- if ("void" != $params[0]["type"]) {\r
- \r
- $msg = "The function inherited some parameter documentation from it's parentclass but PHPDoc could not find\r
- arguments in the function head. Add @param void to the doc comment to avoid confusion.";\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");\r
- \r
- }\r
- \r
- }\r
-\r
- return array();\r
- \r
- }\r
-\r
- // compare the informations from the parser with the @param tags\r
- reset($args);\r
- while (list($k, $arg) = each($args)) {\r
-\r
- if (isset($params[$k])) {\r
-\r
- if ($arg["optional"])\r
- $params[$k]["default"] = $arg["default"];\r
-\r
- if (!$inherited) {\r
-\r
- if ("" != $arg["type"] && "" != $params[$k]["type"] && "mixed" != $params[$k]["type"] && strtolower($arg["type"]) != strtolower($params[$k]["type"])) {\r
-\r
- $type = $arg["type"];\r
- $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
- $this->addNumberSuffix($k + 1),\r
- $arg["name"],\r
- $params[$k]["type"],\r
- $type,\r
- $arg["name"],\r
- (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)",\r
- $type,\r
- (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)"\r
- );\r
-\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");\r
-\r
- } else if ("" != $params[$k]["type"]) {\r
-\r
- $type = $params[$k]["type"];\r
-\r
- } else {\r
-\r
- $msg = sprintf('Type missing for the %s parameter, "mixed" assumed.', $this->addNumberSuffix($k));\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "missing");\r
- $type = "mixed";\r
-\r
- }\r
-\r
- $params[$k]["type"] = $type;\r
-\r
- } else {\r
-\r
- if ("" != $params[$k]["type"] && strtolower($arg["type"]) != strtolower($params[$k]["type"])) {\r
-\r
- $type = (""!=$args["type"]) ? $arg["type"] : $params[$k]["type"];\r
- $msg = sprintf("Possible documentation error due to inherited information.\r
- The type of the %s parameter '%s' does not match the documented type '%s'.\r
- Override the inherited documentation if neccessary.",\r
- $this->addNumberSuffix($k),\r
- $arg["type"],\r
- $params[$k]["type"]\r
- );\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");\r
- \r
- } else if ("" != $params[$k]["type"]) {\r
- \r
- $type = $params[$k]["type"];\r
- \r
- } else {\r
- \r
- $type = "mixed";\r
- $msg = sprintf('Type missing for the %d parameter, "mixed" assumed. Override the inherited documentation if neccessary.', $k);\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");\r
-\r
- }\r
-\r
- $params[$k]["type"] = $type;\r
- \r
- }\r
-\r
- if ("" != $params[$k]["name"] && $arg["name"] != $params[$k]["name"]) {\r
-\r
- $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
- $this->addNumberSuffix($k+1),\r
- $arg["name"],\r
- $params[$k]["name"],\r
- $type,\r
- $arg["name"],\r
- (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)",\r
- $type,\r
- (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)"\r
- );\r
-\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");\r
- $params[$k]["name"] = $arg["name"];\r
-\r
- } else if ("" == $params[$k]["name"]) {\r
-\r
- $params[$k]["name"] = $arg["name"];\r
-\r
- }\r
-\r
- } else {\r
-\r
- $msg = sprintf("%s parameter '%s' is not documented add '@param %s [description]' to the end of the @param[eter] list.",\r
- $this->addNumberSuffix($k+1),\r
- $arg["name"],\r
- ("" == $arg["type"]) ? "(object objectname|type)" : $arg["type"]\r
- );\r
-\r
- $params[$k]["name"] = $arg["name"];\r
- $params[$k]["undoc"] = true;\r
-\r
- if ("" != $arg["type"])\r
- $params[$k]["type"] = $arg["type"];\r
-\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "missing");\r
- }\r
-\r
- }\r
-\r
- // more @params specified than variables where found in the function head, delete them\r
- if ($num_params > $num_args) {\r
-\r
- $msg = "The parser found '$num_args' parameter but '$num_params' @param[eter] tags. You should update the @param[eter] list.";\r
- $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch");\r
- for ($i = $k + 1; $i < $num_params; ++$i)\r
- unset($params[$i]);\r
-\r
- }\r
-\r
- return $params;\r
- } // end func checkArgDocs\r
-\r
-} // end func PhpdocAnalyser\r
-?>\r
projects / atutor.git / blobdiff