mods/phpdoc/PHPDoc/analyser/PhpdocModuleAnalyser.php

   1 <?php\r
   2 /**\r
   3 * Analyses a modulegroup.\r
   4 *\r
   5 * @version $Id: PhpdocModuleAnalyser.php,v 1.4 2000/12/03 22:37:36 uw Exp $\r
   6 */\r
   7 class PhpdocModuleAnalyser extends PhpdocAnalyser {\r
   8 \r
   9         /**\r
  10         * Module data\r
  11         * @var  array\r
  12         */\r
  13         var $modulegroup                = array();\r
  14 \r
  15         /**\r
  16         * List of all modules in the modulegroup\r
  17         * @var  array\r
  18         */ \r
  19         var $modulelist = array();\r
  20         \r
  21         /**\r
  22         * Puuuh - findUndocumented() needs this.\r
  23         * @var  array\r
  24         * @see  findUndocumented()\r
  25         */                                                                                                              \r
  26         var $undocumentedFields = array(\r
  27                                                                                                                         "functions"     => "function",\r
  28                                                                                                                         "uses"                  => "included file",\r
  29                                                                                                                         "consts"                => "constant"\r
  30                                                                                                         );\r
  31 \r
  32         /**\r
  33         * Sets the data of the modulegroup to analyse.\r
  34         * \r
  35         * @param        array   Raw modulegroup data from the parser.\r
  36         * @access       public\r
  37         */\r
  38         function setModulegroup($modulegroup) {\r
  39         \r
  40                 $this->modulegroup = $modulegroup;      \r
  41                 \r
  42         } // end func setModulegroup\r
  43         \r
  44         function analyse() {\r
  45 \r
  46                 $this->flag_get = false;\r
  47                 \r
  48                 $this->buildModulelist();\r
  49                 \r
  50                 $this->updateAccessReturn();\r
  51                 $this->updateBrothersSisters();\r
  52                 $this->checkSee();\r
  53                                 \r
  54                 $this->checkFunctionArgs();\r
  55                 $this->findUndocumented();\r
  56                 \r
  57         } // end func analyse\r
  58         \r
  59         /**\r
  60         * Returns a module from the modulegroup or false if there are no more modules.\r
  61         *\r
  62         * @return       mixed           False if there no more modules in the modulegroup otherwise\r
  63         *                                                               an array with the data of a module.\r
  64         * @access       public\r
  65         */\r
  66         function getModule() {\r
  67         \r
  68                 if (!$this->flag_get) {\r
  69                         reset($this->modulelist);\r
  70                         $this->flag_get = true;\r
  71                 }\r
  72                         \r
  73                 if (list($modulename, $group) = each($this->modulelist)) {\r
  74                         \r
  75                         $module = $this->modulegroup[$group][$modulename];\r
  76                         unset($this->modulegroup[$group][$modulename]);                 \r
  77                         return $module;\r
  78                         \r
  79                 } else {\r
  80                 \r
  81                         return false;\r
  82                         \r
  83                 }\r
  84                 \r
  85         } // end func getModule\r
  86         \r
  87         function findUndocumented() {\r
  88 \r
  89                 reset($this->modulegroup);\r
  90                 while (list($group, $modules) = each($this->modulegroup)) {\r
  91                         \r
  92                         reset($modules);\r
  93                         while (list($name, $module) = each($modules)) {\r
  94                                 \r
  95                                 reset($this->undocumentedFields);\r
  96                                 while (list($index, $eltype) = each($this->undocumentedFields)) {\r
  97                                         if (!isset($module[$index]))\r
  98                                                 continue;\r
  99                                                 \r
 100                                         $file = $module["filename"];\r
 101                                         \r
 102                                         reset($module[$index]);\r
 103                                         while (list($elname, $data) = each($module[$index]))\r
 104                                                 if (isset($data["undoc"]) && $data["undoc"])\r
 105                                                         $this->warn->addDocWarning($file, $eltype, $elname, "Undocumented element.", "missing");\r
 106                                 }\r
 107                                 \r
 108                         }\r
 109                         \r
 110                 }               \r
 111 \r
 112         } // end func findUndocumented\r
 113         \r
 114         function checkFunctionArgs() {\r
 115         \r
 116                 reset($this->modulegroup);\r
 117                 while (list($group, $modules) = each($this->modulegroup)) {\r
 118 \r
 119                         reset($modules);\r
 120                         while (list($name, $module) = each($modules)) {\r
 121                                 if (!isset($module["functions"]))\r
 122                                         continue;\r
 123 \r
 124                                 $file = $module["filename"];\r
 125                                                                 \r
 126                                 reset($module["functions"]);\r
 127                                 while (list($fname, $function) = each($module["functions"])) {\r
 128                                         $this->modulegroup[$group][$name]["functions"][$fname]["params"] = $this->checkArgDocs($function["args"], $function["params"], $fname, $file, false);\r
 129                                         unset($this->modulegroup[$group][$name]["functions"][$fname]["args"]);\r
 130                                 }\r
 131                                 \r
 132                         }\r
 133                         \r
 134                 }\r
 135 \r
 136         } // end func checkFunctionArgs\r
 137         \r
 138         /**\r
 139         * Builds an internal list of all modules in the modulegroup.\r
 140         * @see  $modulelist, $modulegroup\r
 141         */\r
 142         function buildModulelist() {\r
 143         \r
 144                 $this->modulelist = array();\r
 145                 \r
 146                 reset($this->modulegroup);\r
 147                 while (list($group, $modules) = each($this->modulegroup)) {\r
 148                 \r
 149                         reset($modules);\r
 150                         while (list($modulename, $data) = each($modules))\r
 151                                 $this->modulelist[$modulename] = $group;\r
 152                                 \r
 153                 }\r
 154                 \r
 155         }\r
 156 \r
 157                 \r
 158         function updateBrothersSisters() {\r
 159         \r
 160                 reset($this->modulelist);\r
 161                 while (list($modulename, $group) = each($this->modulelist)) {\r
 162                         $this->updateBrotherSisterElements($group, $modulename, "functions");\r
 163                         $this->updateBrotherSisterElements($group, $modulename, "variables");\r
 164                 }       \r
 165                 \r
 166         } // end func updateBrothersSisters\r
 167         \r
 168         /**\r
 169         * @param        string  Modulegroupname\r
 170         * @param        string  Modulename\r
 171         * @param        string  Elementtype: functions, variables.\r
 172         * @return       boolean \r
 173         */\r
 174         function updateBrotherSisterElements($group, $modulename, $type) {\r
 175                 \r
 176                 if (!isset($this->modulegroup[$group][$modulename][$type])) \r
 177                         return false;\r
 178                         \r
 179                 reset($this->modulegroup[$group][$modulename][$type]);\r
 180                 while (list($elementname, $data) = each($this->modulegroup[$group][$modulename][$type])) {\r
 181                         \r
 182                         if (isset($data["brother"])) {\r
 183 \r
 184                                 $name = ("functions" == $type) ? substr($data["brother"], 0, -2) : substr($data["brother"], 1);\r
 185                                 $name = strtolower($name);\r
 186 \r
 187                                 if (!isset($this->modulegroup[$group][$modulename][$type][$name])) {\r
 188                                 \r
 189                                         $this->warn->addDocWarning($this->modulegroup[$group][$modulename]["filename"], $type, $elementname, "Brother '$name' is unknown. Tags gets ignored.", "mismatch");\r
 190                                         unset($this->modulegroup[$group][$modulename][$type][$elementname]["brother"]);\r
 191                                         \r
 192                                 } else {\r
 193                                 \r
 194                                         $this->modulegroup[$group][$modulename][$type][$elementname]["brother"] = $name;\r
 195                                         $this->modulegroup[$group][$modulename][$type][$elementname] = $this->copyBrotherSisterFields($this->modulegroup[$group][$modulename][$type][$elementname], $this->modulegroup[$group][$modulename][$type][$name]);\r
 196                                         \r
 197                                 }\r
 198 \r
 199                         }\r
 200                         \r
 201                 }\r
 202                 \r
 203         } // end func updateBrotherSistersElements\r
 204         \r
 205         function updateAccessReturn() {\r
 206                 \r
 207                 reset($this->modulelist);\r
 208                 while (list($modulename, $group) = each($this->modulelist)) {\r
 209                 \r
 210                         if (!isset($this->modulegroup[$group][$modulename]["access"]))\r
 211                                 $this->modulegroup[$group][$modulename]["access"] = "private";\r
 212                                 \r
 213                         $this->updateAccessReturnElements($group, $modulename, "functions");\r
 214                         $this->updateAccessReturnElements($group, $modulename, "variables");\r
 215                         $this->updateAccessElements($group, $modulename, "consts");             \r
 216                         \r
 217                 }\r
 218                                 \r
 219         } // end func updateAccessReturn\r
 220         \r
 221         /**\r
 222         * @param        string  Modulegroup\r
 223         * @param        string  Modulename\r
 224         * @param        string  Elementtype: functions, variables, consts.\r
 225         * @return       boolean\r
 226         */\r
 227         function updateAccessReturnElements($group, $modulename, $type) {\r
 228                 \r
 229                 if (!isset($this->modulegroup[$group][$modulename][$type]))\r
 230                         return false;\r
 231 \r
 232                 reset($this->modulegroup[$group][$modulename][$type]);\r
 233                 while (list($elementname, $data) = each($this->modulegroup[$group][$modulename][$type])) {\r
 234                 \r
 235                         if (!isset($data["access"])) \r
 236                                 $this->modulegroup[$group][$modulename][$type][$elementname]["access"] = "private";\r
 237                                 \r
 238                         if (!isset($data["return"]))\r
 239                                 $this->modulegroup[$group][$modulename][$type][$elementname]["return"] = "void";\r
 240                                 \r
 241                 }\r
 242                                 \r
 243         } // end func updateAccessReturnElements\r
 244         \r
 245         /**\r
 246         * @param        string  Modulegroup\r
 247         * @param        string  Modulename\r
 248         * @param        string  Elementtype: functions, variables, consts.\r
 249         * @return       boolean\r
 250         */\r
 251         function updateAccessElements($group, $modulename, $type) {\r
 252                 \r
 253                 if (!isset($this->modulegroup[$group][$modulename][$type]))\r
 254                         return false;\r
 255                         \r
 256                 reset($this->modulegroup[$group][$modulename][$type]);\r
 257                 while (list($elementname, $data) = each($this->modulegroup[$group][$modulename][$type])) {\r
 258                         \r
 259                         if (!isset($data["access"])) \r
 260                                 $this->modulegroup[$group][$modulename][$type][$elementname]["access"] = "private";\r
 261                 \r
 262                 }\r
 263                 \r
 264         } // end func updateAccessElements\r
 265         \r
 266         function checkSee() {\r
 267 \r
 268                 reset($this->modulegroup);\r
 269                 while (list($group, $modules) = each($this->modulegroup)) {\r
 270 \r
 271                         while (list($modulename, $module) = each($modules)) {\r
 272                 \r
 273                                 $this->buildElementlist($group, $modulename);\r
 274                                 \r
 275                                 if (isset($module["functions"])) \r
 276                                         $this->checkSeeElements($module["functions"], $group, $modulename, "functions");\r
 277                                         \r
 278                                 if (isset($module["variables"]))\r
 279                                         $this->checkSeeElements($module["variables"], $group, $modulename, "variables");\r
 280                                 \r
 281                                 if (isset($module["consts"])) \r
 282                                         $this->checkSeeElements($module["consts"], $group, $modulename, "consts");\r
 283                                         \r
 284                                 if (isset($module["uses"]))\r
 285                                         $this->checkSeeElements($module["uses"], $group, $modulename, "uses");\r
 286                                 \r
 287                         }       \r
 288                         \r
 289                 }\r
 290                 \r
 291         } // end func checkSee\r
 292 \r
 293         /**\r
 294         * Checks see references in the given element array (functions, variables...)\r
 295         *\r
 296         * References to variables and functions within the same module get checked.\r
 297         * It the references element does not exist, the reference gets deleted and \r
 298         * a doc warning gets generated.\r
 299         * \r
 300         * @param        array           List of functions, variables,...\r
 301         * @param        string  Name of the modulegroup that contains the given elements.\r
 302         * @param        string  Name of the module that contains the given elements.\r
 303         * @param        string  Elementtype: functions, variables, consts, uses.\r
 304         */      \r
 305         function checkSeeElements($elements, $modulegroup, $modulename, $eltype) {\r
 306 \r
 307                 reset($elements);\r
 308                 while (list($elname, $element) = each($elements)) {\r
 309                 \r
 310                         if (isset($element["see"])) {\r
 311                                 \r
 312                                 if (isset($element["see"]["var"])) {\r
 313                                         \r
 314                                         reset($element["see"]["var"]);\r
 315                                         while (list($k, $variable) = each($element["see"]["var"])) \r
 316                                                 if (!isset($this->elementlist["variables"][strtolower($variable["name"])])) {\r
 317                                                         $this->warn->addDocWarning($this->modulegroup[$modulegroup][$modulename]["filename"], "variables", $elname, "@see referrs to the variable '" . $variable["name"] . "' which is not defined in the class. Entry gets ignored.", "mismatch");\r
 318                                                         unset($this->modulegroup[$modulegroup][$modulename][$eltype][$elname]["see"]["var"][$k]);\r
 319                                                 }\r
 320 \r
 321                                 }\r
 322                                 \r
 323                                 if (isset($element["see"]["function"])) {\r
 324                                         \r
 325                                         reset($element["see"]["function"]);\r
 326                                         while (list($k, $function) = each($element["see"]["function"]))\r
 327                                                 if (!isset($this->elementlist["functions"][strtolower(substr($function["name"], 0, -2))])) {\r
 328                                                         $this->warn->addDocWarning($this->modulegroup[$modulename]["filename"], "functions", $elname, "@see referrs to the function '" . $function["name"] . "' which is not defined in the class. Entry gets ignored.", "mismatch");\r
 329                                                         unset($this->modulegroup[$modulegroup][$modulename][$eltype][$elname]["see"]["function"][$k]);\r
 330                                                 }\r
 331 \r
 332                                 }\r
 333                                 \r
 334                         }\r
 335                         \r
 336                 }       \r
 337                 \r
 338         } // end func checkSeeElement\r
 339         \r
 340         /**\r
 341         * Builds an array with all elements of a class and saves it to $this->elementlist.\r
 342         * \r
 343         * @param        string  Name of the modulegroup that contains the module.\r
 344         * @param        string  Name of the module to scan.\r
 345         */\r
 346         function buildElementlist($modulegroup, $modulename) {\r
 347                 \r
 348                 $elements = array();\r
 349                 $fields = array("functions", "variables", "consts", "uses");\r
 350                 \r
 351                 reset($fields);\r
 352                 while (list($k, $field) = each($fields)) \r
 353                         if (isset($this->modulegroup[$modulegroup][$modulename][$field])) {\r
 354                                 \r
 355                                 reset($this->modulegroup[$modulegroup][$modulename][$field]);\r
 356                                 while (list($element, ) = each($this->modulegroup[$modulegroup][$modulename][$field])) \r
 357                                         $elements[$field][$element] = true;\r
 358                                         \r
 359                         }\r
 360                 \r
 361                 $this->elementlist = $elements;\r
 362                 \r
 363         } // end func buildElementlist\r
 364         \r
 365 } // end class PhpdocModuleAnalyser\r
 366 ?>