mods/phpdoc/PHPDoc/parser/PhpdocModuleParser.php

   1 <?php\r
   2 /**\r
   3 * Extracts modules and their documentation from php code.\r
   4 * @author       Ulf Wendel <ulf.wendel@redsys.de>\r
   5 * @version 0.1alpha\r
   6 */\r
   7 class PhpdocModuleParser extends PhpdocConstantParser {\r
   8 \r
   9         /**\r
  10         * Empty hash that shows the structure of a module.\r
  11         * @var  array\r
  12         */\r
  13         var $emptyModule = array(\r
  14         \r
  15                                                                                                                 "name"                          => "",\r
  16                                                                                                                 "group"                         => "",\r
  17                                                                                                                 "undoc"                         => true,\r
  18                                                                                                                 \r
  19                                                                                                                 "functions"             => array(),\r
  20                                                                                                                 "consts"                        => array(),\r
  21                                                                                                                 "uses"                          => array()\r
  22                                                                                                 );\r
  23 \r
  24         /**\r
  25         * List of tags allowed within a module doc comment.\r
  26         * @var  array   tagname => true\r
  27         */                                                                                                      \r
  28         var $moduleTags = array(\r
  29                                                                                                                 "module"                        => true,\r
  30                                                                                                                 "modulegroup"   => true,\r
  31                                                                                                                 \r
  32                                                                                                                 "access"                        => true,\r
  33                                                                                                                 \r
  34                                                                                                                 "see"                                   => true,\r
  35                                                                                                                 "link"                          => true,\r
  36                                                                                                                 \r
  37                                                                                                                 "author"                        => true,\r
  38                                                                                                                 "copyright"             => true,\r
  39                                                                                                                 \r
  40                                                                                                                 "version"                       => true,\r
  41                                                                                                                 "since"                         => true,\r
  42                                                                                                                 \r
  43                                                                                                                 "deprecated"    => true,\r
  44                                                                                                                 "deprec"                        => true,\r
  45                                                                                                                 \r
  46                                                                                                                 "brother"                       => true,\r
  47                                                                                                                 "sister"                        => true,\r
  48                                                                                                                 \r
  49                                                                                                                 "exclude"               => true,\r
  50                                                                                                                 \r
  51                                                                                                                 "package"                       => true,\r
  52                                                                                                                 \r
  53                                                                                                                 "magic"                         => true,\r
  54                                                                                                                 "todo"                          => true\r
  55                                                                                                 );\r
  56 \r
  57         /**\r
  58         * Hash of all module groups\r
  59         * @var  array\r
  60         */\r
  61         var $moduleGroups = array();\r
  62         \r
  63         /**\r
  64         * Central module parsing function.\r
  65         *\r
  66         * @param        array           Array of parsing data\r
  67         * @return       array           \r
  68         * @see  analyseModuleDoc()\r
  69         */\r
  70         function analyseModule($para) {\r
  71                 \r
  72                 $module = $this->analyseModuleDoc($para["modules"]);                    \r
  73                 unset($para["modules"]);\r
  74 \r
  75                 $this->moduleGroups[$module["group"]][] = $module["name"];\r
  76 \r
  77                 reset($para["functions"]);\r
  78                 while (list($k, $data)=each($para["functions"]))\r
  79                         $module["functions"][strtolower($data["name"])] = $this->analyseFunction($data);\r
  80                 unset($para["functions"]);\r
  81                         \r
  82                 reset($para["consts"]);\r
  83                 while (list($k, $data)=each($para["consts"]))\r
  84                         $module["consts"][strtolower($data["name"])] = $this->analyseConstant($data);\r
  85                 unset($para["const"]);\r
  86                 \r
  87                 reset($para["uses"]);\r
  88                 while (list($k, $data)=each($para["uses"]))\r
  89                         $module["uses"][strtolower($data["file"])] = $this->analyseUse($data);\r
  90                 \r
  91                 return $module;\r
  92         } // end func analyseModule\r
  93         \r
  94         /**\r
  95         * Extracts the allowed documentation tags out of a module doc comment.\r
  96         * \r
  97         * @param        array   Module paragraph\r
  98         * @return       array           \r
  99         */\r
 100         function analyseModuleDoc($para) {\r
 101         \r
 102                 $module = $this->emptyModule;\r
 103                 $module["name"] = (""!=$para["name"]) ? $para["name"] : $this->currentFile;\r
 104                 $module["group"] = (""!=$para["group"]) ? $para["group"] : $this->currentFile;\r
 105                 \r
 106                 if ("missing" == $para["status"]) {\r
 107                         \r
 108                         $msg = "The file '$this->currentFile' does not contain any classes and seems to lack a module doc comment.";\r
 109                         $this->warn->addDocWarning($this->currentFile, "module", $module["name"], $msg, "missing");\r
 110                         \r
 111                 } else if ("tags missing" == $para["status"]) {\r
 112                 \r
 113                         $msg = "The module doc comment does not contain a @module or @modulegroup tag, the module gets names: '$this->currentFile'";\r
 114                         $this->warn->addDocWarning($this->currentFile, "module", $module["name"], $msg, "missing");\r
 115                 \r
 116                 }\r
 117                 \r
 118                 if (""!=$para["doc"]) {         \r
 119                         \r
 120                         $tags   = $this->getTags($para["doc"]);\r
 121                         $module = $this->analyseTags($tags, $module, $this->moduleTags);\r
 122                         \r
 123                         list($msg, $module) = $this->checkParserErrors($module, "module");\r
 124                         if (""!=$msg) \r
 125                                 $this->warn->addDocWarning($this->currentFile, "module", $module["name"], $msg, "mismatch");\r
 126                         \r
 127                         list($shortdesc, $fulldesc) = $this->getDescription($para["doc"]);                      \r
 128                         $module["sdesc"] = $shortdesc;\r
 129                         $module["desc"]  = $fulldesc;\r
 130                 \r
 131                         $module["undoc"] = false;\r
 132                 }\r
 133 \r
 134                 unset($module["module"]);\r
 135                 unset($module["modulegroup"]);\r
 136                 \r
 137                 return $module;         \r
 138         } // end analyseModuleDoc\r
 139         \r
 140 } // end class PhpdocModuleParser\r
 141 ?>