cvs: php4 /pear/PHPDoc/analyser PhpdocAnalyser.php PhpdocClassAnalyser.php PhpdocModuleAnalyser.php /pear/PHPDoc/core Phpdoc.php
PhpdocSetupHandler.php /pear/PHPDoc/parser PhpdocParserCore.php

uw Sat Dec 2 16:37:59 2000 EDT Modified files: /php4/pear/PHPDoc/analyser PhpdocAnalyser.php PhpdocClassAnalyser.php PhpdocModuleAnalyser.php /php4/pear/PHPDoc/core Phpdoc.php PhpdocSetupHandler.php /php4/pear/PHPDoc/parser PhpdocParserCore.php Log: - reformatted some files Please use tabs (size: 2 spaces) to indent the source. Do not replace tabs with spaces when you apply changed to PHPDoc. - renamed add_number_suffix to addNumberSuffix - changed the meaning of the placeholder {DESCRIPTION} in the templates The internal array index "desc", the XML container <description> and the template placeholder {DESCRIPTION} contained the "short description" (first sentence of a doc comment) and the "long description" (everything from the first sentence to the first doc tag) before the change. Now they do not contain the short description as well but only the long description. - fixed @brother/@sister Elements that use @brother/@sister now inherit all fields from the specified brother/sister that are not defined (or empty) in their own doc comment. I hope this was the last "### PANIK ###" (panic, fixme) in the code.

Index: php4/pear/PHPDoc/analyser/PhpdocAnalyser.php diff -u php4/pear/PHPDoc/analyser/PhpdocAnalyser.php:1.2 php4/pear/PHPDoc/analyser/PhpdocAnalyser.php:1.3 --- php4/pear/PHPDoc/analyser/PhpdocAnalyser.php:1.2 Sat Oct 14 10:39:13 2000 +++ php4/pear/PHPDoc/analyser/PhpdocAnalyser.php Sat Dec 2 16:37:58 2000 @@ -1,284 +1,321 @@ -<?php -/** -* Analyses parsing data. -* -* Analyse means: -* - update @brother/@sister -* - update @access/@return -* - inherit elements -* - inherit information -* -*/ -class PhpdocAnalyser extends PhpdocObject { - - /** - * Flag indicating that getModule/getClass was called. - * @var boolean - */ - var $flag_get = false; - - /** - * Adds a suffix to the number like 1st, 2nd and 3th - * - * @param integer $nr number to format - * @return string - * @author Thomas Weinert <subjective@subjective.de> - */ - function add_number_suffix($nr) { - $last_nr = substr($nr,-1,1); - switch ($last_nr) { - case 1 : return ($nr."st"); break; - case 2 : return ($nr."nd"); break; - default : return ($nr."th"); - } - } - /** - * Starts the analysing of the raw parsing data. - * - * @access public - * @abstract - */ - function analyse() { - } // end func analyse - - /** - * Handles @brother and @sister. - * @abstract - * @see updateBrotherSister - */ - function updateBrothersSisters() { - } // end func updateBrothersSisters - - /** - * Updates certain elements that use @brother and @sister. - * - * @return boolean $ok - */ - function updateBrotherSisterElements() { - return false; - } // end func updateBrotherSisterElements - - /** - * Updates the @access and @return tag values. - * - * @see updateAccessReturnElements(), updateAccessElements() - * @abstract - */ - function updateAccessReturn() { - } // end func updateAccessReturn - - /** - * Updates @access and @return for certain elements. - * - * This function should only be used to update functions. - * Functions that have the same name as the class (constructors) - * get @return void and @access public. Functions without - * @access get @access public and functions without @return get - * @return void. - * - * @return boolean $ok - * @see updateAccessReturn() - * @abstract - */ - function updateAccessReturnElements() { - return false; - } // end func updateAccessReturnElements - - /** - * Updates @access tags. - * - * @see updateAccessReturnElements() - * @abstract - */ - function updateAccessElements() { - } // end func updateAccessElements - - /** - * Compares the @param tags with the function head found. - * @abstract - */ - function checkFunctionArgs() { - } // end func checkFunctionArgs - - /** - * Looks for undocumented elements and adds a warning if neccessary. - * @abstract - */ - function findUndocumented() { - } // end func findUndocumented - - /** - * Compares the argument list generated from the function head with the @param tags found. - * - * PHPDoc is able to recognize these documentation mistakes: - * - too few or too many @param tags - * - name does not match or is missing - * - type does not match or is missing - * - trouble with inherited elements - * - * @param array Function arguments found by the parser - * @param array Paramarray - * @param string Functionname - * @param string Filename - * @param boolean Param tags inherited? - * @return array $params Param array - */ - function checkArgDocs($args, $params, $elname, $elfile, $inherited=false) { - - // "args" contains the informations the parser found in the function head. - // "param" contains the information from the @param tags. - $num_args = count($args); - $num_params = count($params); - - // no args? return... - if (0==$num_args && 0==$num_params) { - return array(); - } - - // no args but @param used - if (0==$num_args && $num_params>0) { - - if (!$inherited) { - - $msg = "Function head shows no parameters, remove all @param tags."; - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); - - } else { - - if ("void"!=$params[0]["type"]) { - - $msg = "The function inherited some parameter documentation from it's parentclass but PHPDoc could not find - arguments in the function head. Add @param void to the doc comment to avoid confusion."; - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); - - } - - } - - return array(); - - } - // compare the informations from the parser with the @param tags - reset($args); - while (list($k, $arg)=each($args)) { - - if (isset($params[$k])) { - - if ($arg["optional"]) - $params[$k]["default"] = $arg["default"]; - - if (!$inherited) { - - if (""!=$arg["type"] && ""!=$params[$k]["type"] && strtolower($arg["type"])!=strtolower($params[$k]["type"])) { - - $type = $arg["type"]; - $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.", - $this->add_number_suffix($k+1), - $arg["name"], - $params[$k]["type"], - $type, - $arg["name"], - (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)", - $type, - (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)" - ); - /* end of changes */ - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); - - } else if (""!=$params[$k]["type"]) { - - $type = $params[$k]["type"]; - - } else { - - $msg = sprintf('Type missing for the %s parameter, "mixed" assumed.', $this->add_number_suffix($k)); - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "missing"); - $type = "mixed"; - - } - $params[$k]["type"] = $type; - - } else { - - if (""!=$params[$k]["type"] && strtolower($arg["type"])!=strtolower($params[$k]["type"])) { - - $type = (""!=$args["type"]) ? $arg["type"] : $params[$k]["type"]; - $msg = sprintf("Possible documentation error due to inherited information. - The type of the %s parameter '%s' does not match the documented type '%s'. - Override the inherited documentation if neccessary.", - $this->add_number_suffix($k), - $arg["type"], - $params[$k]["type"] - ); - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); - - } else if (""!=$params[$k]["type"]) { - - $type = $params[$k]["type"]; - - } else { - - $type = "mixed"; - $msg = sprintf('Type missing for the %d parameter, "mixed" assumed. Override the inherited documentation if neccessary.', $k); - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); - - } - $params[$k]["type"] = $type; - - } - - if (""!=$params[$k]["name"] && $arg["name"]!=$params[$k]["name"]) { - - $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.", - $this->add_number_suffix($k+1), - $arg["name"], - $params[$k]["name"], - $type, - $arg["name"], - (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)", - $type, - (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)" - ); - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); - $params[$k]["name"] = $arg["name"]; - - } else if (""==$params[$k]["name"]) { - - $params[$k]["name"] = $arg["name"]; - - } - - } else { - - $msg = sprintf("%s parameter '%s' is not documented add '@param %s [description]' to the end of the @param[eter] list.", - $this->add_number_suffix($k+1), - $arg["name"], - (""==$arg["type"]) ? "(object objectname|type)" : $arg["type"] - ); - - $params[$k]["name"] = $arg["name"]; - $params[$k]["undoc"] = true; - - if (""!=$arg["type"]) - $params[$k]["type"] = $arg["type"]; - - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "missing"); - } - - } - - // more @params specified than variables where found in the function head, delete them - if ($num_params>$num_args) { - - $msg = "The parser found '$num_args' parameter but '$num_params' @param[eter] tags. You should update the @param[eter] list."; - $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); - for ($i=$k+1; $i<$num_params; $i++) - unset($params[$i]); - - } - - return $params; - } // end func checkArgDocs - -} // end func PhpdocAnalyser +<?php +/** +* Analyses parsing data. +* +* Analyse means: +* - update @brother/@sister +* - update @access/@return +* - inherit elements +* - inherit information +* +*/ +class PhpdocAnalyser extends PhpdocObject { + + /** + * Flag indicating that getModule/getClass was called. + * @var boolean + */ + var $flag_get = false; + + /** + * Adds a suffix to the number like 1st, 2nd and 3th + * + * @param integer $nr number to format + * @return string + * @author Thomas Weinert <subjective@subjective.de> + */ + function addNumberSuffix($nr) { + + $last_nr = substr($nr, -1, 1); + + switch ($last_nr) { + case 1: + return ($nr."st"); + break; + + case 2: + return ($nr."nd"); + break; + + default: + return ($nr."th"); + } + + } // end func addNumberSuffix + + /** + * Starts the analysing of the raw parsing data. + * + * @access public + * @abstract + */ + function analyse() { + ; + } // end func analyse + + /** + * Handles @brother and @sister. + * + * @abstract + * @see updateBrotherSister + */ + function updateBrothersSisters() { + ; + } // end func updateBrothersSisters + + /** + * Updates certain elements that use @brother and @sister. + * + * @return boolean $ok + */ + function updateBrotherSisterElements() { + return false; + } // end func updateBrotherSisterElements + + /** + * Copies fields from a brother or sister to the current element. + * + * @param array Data of the target element that has a @brother/@sister tag + * @param array Data of the element that is referenced by @brother/@sister + */ + function copyBrotherSisterFields($target, $from) { + + reset($from); + while (list($k, $v) = each($from)) + if (!isset($target[$k]) || "" == $target[$k]) + $target[$k] = $v; + + return $target; + } // end func copyBrotherSisterFields + + /** + * Updates the @access and @return tag values. + * + * @see updateAccessReturnElements(), updateAccessElements() + * @abstract + */ + function updateAccessReturn() { + ; + } // end func updateAccessReturn + + /** + * Updates @access and @return for certain elements. + * + * This function should only be used to update functions. + * Functions that have the same name as the class (constructors) + * get @return void and @access public. Functions without + * @access get @access public and functions without @return get @return void. + * + * @return boolean $ok + * @see updateAccessReturn() + * @abstract + */ + function updateAccessReturnElements() { + ; + } // end func updateAccessReturnElements + + /** + * Updates @access tags. + * + * @see updateAccessReturnElements() + * @abstract + */ + function updateAccessElements() { + ; + } // end func updateAccessElements + + /** + * Compares the @param tags with the function head found. + * + * @abstract + */ + function checkFunctionArgs() { + ; + } // end func checkFunctionArgs + + /** + * Looks for undocumented elements and adds a warning if neccessary. + * + * @abstract + */ + function findUndocumented() { + ; + } // end func findUndocumented + + /** + * Compares the argument list generated from the function head with the @param tags found. + * + * PHPDoc is able to recognize these documentation mistakes: + * - too few or too many @param tags + * - name does not match or is missing + * - type does not match or is missing + * - trouble with inherited elements + * + * @param array Function arguments found by the parser + * @param array Paramarray + * @param string Functionname + * @param string Filename + * @param boolean Param tags inherited? + * @return array $params Param array + */ + function checkArgDocs($args, $params, $elname, $elfile, $inherited = false) { + + // "param" contains the information from the @param tags. + $num_args = count($args); + $num_params = count($params); + + // no args? return... + if (0 == $num_args && 0 == $num_params) + return array(); + + // no args but @param used + if (0 == $num_args && $num_params > 0) { + + if (!$inherited) { + + $msg = "Function head shows no parameters, remove all @param tags."; + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); + + } else { + + if ("void" != $params[0]["type"]) { + + $msg = "The function inherited some parameter documentation from it's parentclass but PHPDoc could not find + arguments in the function head. Add @param void to the doc comment to avoid confusion."; + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); + + } + + } + + return array(); + + } + + // compare the informations from the parser with the @param tags + reset($args); + while (list($k, $arg) = each($args)) { + + if (isset($params[$k])) { + + if ($arg["optional"]) + $params[$k]["default"] = $arg["default"]; + + if (!$inherited) { + + if ("" != $arg["type"] && "" != $params[$k]["type"] && "mixed" != $params[$k]["type"] && strtolower($arg["type"]) != strtolower($params[$k]["type"])) { + + $type = $arg["type"]; + $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.", + $this->addNumberSuffix($k + 1), + $arg["name"], + $params[$k]["type"], + $type, + $arg["name"], + (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)", + $type, + (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)" + ); + + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); + + } else if ("" != $params[$k]["type"]) { + + $type = $params[$k]["type"]; + + } else { + + $msg = sprintf('Type missing for the %s parameter, "mixed" assumed.', $this->addNumberSuffix($k)); + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "missing"); + $type = "mixed"; + + } + + $params[$k]["type"] = $type; + + } else { + + if ("" != $params[$k]["type"] && strtolower($arg["type"]) != strtolower($params[$k]["type"])) { + + $type = (""!=$args["type"]) ? $arg["type"] : $params[$k]["type"]; + $msg = sprintf("Possible documentation error due to inherited information. + The type of the %s parameter '%s' does not match the documented type '%s'. + Override the inherited documentation if neccessary.", + $this->addNumberSuffix($k), + $arg["type"], + $params[$k]["type"] + ); + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); + + } else if ("" != $params[$k]["type"]) { + + $type = $params[$k]["type"]; + + } else { + + $type = "mixed"; + $msg = sprintf('Type missing for the %d parameter, "mixed" assumed. Override the inherited documentation if neccessary.', $k); + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); + + } + + $params[$k]["type"] = $type; + + } + + if ("" != $params[$k]["name"] && $arg["name"] != $params[$k]["name"]) { + + $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.", + $this->addNumberSuffix($k+1), + $arg["name"], + $params[$k]["name"], + $type, + $arg["name"], + (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)", + $type, + (isset($params[$k]["desc"])) ? $params[$k]["desc"] : "(description)" + ); + + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); + $params[$k]["name"] = $arg["name"]; + + } else if ("" == $params[$k]["name"]) { + + $params[$k]["name"] = $arg["name"]; + + } + + } else { + + $msg = sprintf("%s parameter '%s' is not documented add '@param %s [description]' to the end of the @param[eter] list.", + $this->addNumberSuffix($k+1), + $arg["name"], + ("" == $arg["type"]) ? "(object objectname|type)" : $arg["type"] + ); + + $params[$k]["name"] = $arg["name"]; + $params[$k]["undoc"] = true; + + if ("" != $arg["type"]) + $params[$k]["type"] = $arg["type"]; + + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "missing"); + } + + } + + // more @params specified than variables where found in the function head, delete them + if ($num_params > $num_args) { + + $msg = "The parser found '$num_args' parameter but '$num_params' @param[eter] tags. You should update the @param[eter] list."; + $this->warn->addDocWarning($elfile, "function", $elname, $msg, "mismatch"); + for ($i = $k + 1; $i < $num_params; ++$i) + unset($params[$i]); + + } + + return $params; + } // end func checkArgDocs + +} // end func PhpdocAnalyser ?> Index: php4/pear/PHPDoc/analyser/PhpdocClassAnalyser.php diff -u php4/pear/PHPDoc/analyser/PhpdocClassAnalyser.php:1.1 php4/pear/PHPDoc/analyser/PhpdocClassAnalyser.php:1.2 --- php4/pear/PHPDoc/analyser/PhpdocClassAnalyser.php:1.1 Sun Oct 8 03:03:18 2000 +++ php4/pear/PHPDoc/analyser/PhpdocClassAnalyser.php Sat Dec 2 16:37:58 2000 @@ -343,7 +343,7 @@ return false; reset($this->classes[$classname][$type]); - while (list($elementname, $data)=each($this->classes[$classname][$type])) { + while (list($elementname, $data) = each($this->classes[$classname][$type])) { if (isset($data["brother"])) { @@ -358,8 +358,8 @@ } else { $this->classes[$classname][$type][$elementname]["brother"] = $name; - #### PANIK ### - + $this->classes[$classname][$type][$elementname] = $this->copyBrotherSisterFields($this->classes[$classname][$type][$elementname], $this->classes[$classname][$type][$name]); + } } Index: php4/pear/PHPDoc/analyser/PhpdocModuleAnalyser.php diff -u php4/pear/PHPDoc/analyser/PhpdocModuleAnalyser.php:1.1 php4/pear/PHPDoc/analyser/PhpdocModuleAnalyser.php:1.2 --- php4/pear/PHPDoc/analyser/PhpdocModuleAnalyser.php:1.1 Sun Oct 8 03:03:18 2000 +++ php4/pear/PHPDoc/analyser/PhpdocModuleAnalyser.php Sat Dec 2 16:37:58 2000 @@ -176,10 +176,15 @@ $name = strtolower($name); if (!isset($this->modulegroup[$group][$modulename][$type][$name])) { + $this->warn->addDocWarning($this->modulegroup[$group][$modulename]["filename"], $type, $elementname, "Brother '$name' is unknown. Tags gets ignored.", "mismatch"); unset($this->modulegroup[$group][$modulename][$type][$elementname]["brother"]); + } else { + $this->modulegroup[$group][$modulename][$type][$elementname]["brother"] = $name; + $this->modulegroup[$group][$modulename][$type][$elementname] = $this->copyBrotherSisterFields($this->modulegroup[$group][$modulename][$type][$elementname], $this->modulegroup[$group][$modulename][$type][$name]); + } } Index: php4/pear/PHPDoc/core/Phpdoc.php diff -u php4/pear/PHPDoc/core/Phpdoc.php:1.2 php4/pear/PHPDoc/core/Phpdoc.php:1.3 --- php4/pear/PHPDoc/core/Phpdoc.php:1.2 Sun Oct 15 06:33:12 2000 +++ php4/pear/PHPDoc/core/Phpdoc.php Sat Dec 2 16:37:58 2000 @@ -1,228 +1,237 @@ -<?php -/** -* Coordinates several Phpdoc Object to parse and render source files. -* -* @access public -*/ -class Phpdoc extends PhpdocSetupHandler { - - /** - * Result from the indexer - * @var array $indexer - * @see render() - */ - var $indexer_result = array(); - - /** - * Print status messages - */ - var $flag_output = true; - - /** - * Calls the command line handler if necessary. - * - * @global $argc, $PHP_SELF - */ - function Phpdoc() { - global $argc, $PHP_SELF; - - $this->target = $PHP_SELF."apidoc/"; - - if ($argc>1) - $this->handleArgv(); - } // end constructor - - - /** - * Starts the parser. - * - * @return bool $ok - * @throws PhpdocError - * @access public - * @see - */ - function parse() { - - $this->warn = new PhpdocWarning; - - $errors = $this->checkStatus(); - if (0!=count($errors)) { - - reset($errors); - while (list($k, $error)=each($errors)) - $this->err[] = new PhpdocError($error["msg"]."Errno = ".$error["errno"], 9, __FILE__, __LINE__); - - return false; - } - - $this->outl("Parser starts..."); - - // create some objects - $fileHandler = new PhpdocFileHandler; - $parser = new PhpdocParser(true); - - $classAnalyser = new PhpdocClassAnalyser; - $moduleAnalyser = new PhpdocModuleAnalyser; - - $indexer = new PhpdocIndexer; - - $classExporter = new PhpdocXMLClassExporter(); - $classExporter->setPath($this->target); - - $moduleExporter = new PhpdocXMLModuleExporter(); - $moduleExporter->setPath($this->target); - - $indexExporter = new PhpdocXMLIndexExporter(); - $indexExporter->setPath($this->target); - - $warningExporter = new PhpdocXMLWarningExporter(); - $warningExporter->setPath($this->target); - - // This will change one fine day! - $parser->warn = $this->warn; - $classAnalyser->warn = $this->warn; - $moduleAnalyser->warn = $this->warn; - $classExporter->warn = $this->warn; - $moduleExporter->warn = $this->warn; - $indexer->warn = $this->warn; - - $sourcefiles = $fileHandler->getFilesInDirectory($this->sourceDirectory, $this->sourceFileSuffix); - $parser->setPhpSourcecodeFiles($fileHandler->get($sourcefiles)); - - $this->outl("... preparse to find modulegroups and classtrees."); - $parser->preparse(); - - $this->outl("... parsing classes."); - while ($classtree = $parser->getClassTree()) { - - $classAnalyser->setClasses( $classtree, $parser->current_baseclass ); - $classAnalyser->analyse(); - - while ($class = $classAnalyser->getClass()) { - $indexer->addClass($class); - $classExporter->export($class); - } - - if (floor(phpversion())>3) { - $indexExporter->exportClasstree($indexer->getClasstree(), $parser->current_baseclass); - } else { - $classtree = $indexer->getClasstree(); - $base = $parser->current_baseclass; - $indexExporter->exportClasstree($classtree, $base); - } - - } - - $this->outl("... parsing modules."); - while ($modulegroup = $parser->getModulegroup()) { - - $moduleAnalyser->setModulegroup( $modulegroup ); - $moduleAnalyser->analyse(); - - while ($module = $moduleAnalyser->getModule()) { - $indexer->addModule($module); - $moduleExporter->export($module); - } - - if (floor(phpversion())>3) { - $indexExporter->exportModulegroup($indexer->getModulegroup()); - } else { - $modulegroup = $indexer->getModulegroup(); - $indexExporter->exportModulegroup($modulegroup); - } - - } - - $this->outl("... writing packagelist."); - - if (floor(phpversion())>3) { - $indexExporter->exportPackagelist($indexer->getPackages()); - $indexExporter->exportElementlist($indexer->getElementlist()); - } else { - $packages = $indexer->getPackages(); - $indexExporter->exportPackagelist($packages); - $elements = $indexer->getElementlist(); - $indexExporter->exportElementlist($elements); - } - - $warningExporter->export($parser->warn->getWarnings(), "parser"); - $warningExporter->export($moduleAnalyser->warn->getWarnings(), "moduleanalyser"); - $warningExporter->export($classAnalyser->warn->getWarnings(), "classanalyser"); - $this->outl("Parser finished."); - - return true; - } // end func parse - - /** - * Renders the PHPDoc XML files as HTML files - * - * @param string Targetformat, currently only "html" is available. - * @param string Target directory for the html files - * @param string Directory with the html templates - * @return bool $ok - * @throws PhpdocError - * @access public - */ - function render($type="html", $target="", $template="") { - - $this->outl("Starting to render..."); - - $target = (""==$target) ? $this->target : $this->getCheckedDirname($target); - $template = (""==$template) ? $this->templateRoot : $this->getCheckedDirname($template); - - switch(strtolower($type)) { - - case "html": - default: - $renderer = new PhpdocHTMLRendererManager($target, $template, $this->application, $this->targetFileSuffix); - break; - } - - $fileHandler = new PhpdocFileHandler; - $files = $fileHandler->getFilesInDirectory($target, "xml"); - $len = strlen($target); - - $tpl = new IntegratedTemplate($this->templateRoot); - $tpl->loadTemplateFile("xmlfiles.html"); - $tpl->setCurrentBlock("file_loop"); - - // Do not change the file prefixes! - reset($files); - while (list($k, $file)=each($files)) { - - $tpl->setVariable("FILE", substr($file, $len)); - $tpl->parseCurrentBlock(); - - if ("class_" == substr($file, $len, 6)) { - - $renderer->render(substr($file, $len), "class"); - - } else if ("module_" == substr($file, $len, 7)) { - - $renderer->render(substr($file, $len), "module"); - - } else if ("classtree_" == substr($file, $len, 10)) { - - $renderer->render(substr($file, $len), "classtree"); - - } else if ("modulegroup_" == substr($file, $len, 12)) { - - $renderer->render(substr($file, $len), "modulegroup"); - - } else if ("warnings_" == substr($file, $len, 9)) { - - $renderer->render(substr($file, $len), "warning"); - - } - - } - - $renderer->finish(); - $fileHandler->createFile($target."phpdoc_xmlfiles".$this->targetFileSuffix, $tpl->get()); - - $this->outl($this->finishInstructions); - return true; - } // end func render - -} // end class Phpdoc +<?php +/** +* Coordinates several Phpdoc Object to parse and render source files. +* +* @access public +*/ +class Phpdoc extends PhpdocSetupHandler { + + /** + * Result from the indexer + * @var array $indexer + * @see render() + */ + var $indexer_result = array(); + + /** + * Print status messages + */ + var $flag_output = true; + + /** + * Calls the command line handler if necessary. + * + * @global $argc, $PHP_SELF + */ + function Phpdoc() { + global $argc, $PHP_SELF; + + $this->target = $PHP_SELF."apidoc/"; + + if ($argc>1) + $this->handleArgv(); + + } // end constructor + + /** + * Starts the parser. + * + * @return bool $ok + * @throws PhpdocError + * @access public + * @see + */ + function parse() { + + $this->warn = new PhpdocWarning; + + $errors = $this->checkStatus(); + if (0 != count($errors)) { + + reset($errors); + while (list($k, $error)=each($errors)) + $this->err[] = new PhpdocError($error["msg"]."Errno = ".$error["errno"], 9, __FILE__, __LINE__); + + return false; + } + + $this->outl("Parser starts..."); + + // create some objects + $fileHandler = new PhpdocFileHandler; + $parser = new PhpdocParser(true); + $classAnalyser = new PhpdocClassAnalyser; + $moduleAnalyser = new PhpdocModuleAnalyser; + + $indexer = new PhpdocIndexer; + + $classExporter = new PhpdocXMLClassExporter(); + $classExporter->setPath($this->target); + + $moduleExporter = new PhpdocXMLModuleExporter(); + $moduleExporter->setPath($this->target); + + $indexExporter = new PhpdocXMLIndexExporter(); + $indexExporter->setPath($this->target); + + $warningExporter = new PhpdocXMLWarningExporter(); + $warningExporter->setPath($this->target); + + // This will change one fine day! + $parser->warn = $this->warn; + $classAnalyser->warn = $this->warn; + $moduleAnalyser->warn = $this->warn; + $classExporter->warn = $this->warn; + $moduleExporter->warn = $this->warn; + $indexer->warn = $this->warn; + + $sourcefiles = $fileHandler->getFilesInDirectory($this->sourceDirectory, $this->sourceFileSuffix); + $parser->setPhpSourcecodeFiles($fileHandler->get($sourcefiles)); + + $this->outl("... preparse to find modulegroups and classtrees."); + $parser->preparse(); + + $this->outl("... parsing classes."); + while ($classtree = $parser->getClassTree()) { + + $classAnalyser->setClasses( $classtree, $parser->current_baseclass ); + $classAnalyser->analyse(); + + while ($class = $classAnalyser->getClass()) { + $indexer->addClass($class); + $classExporter->export($class); + } + + if (floor(phpversion()) > 3) { + + $indexExporter->exportClasstree($indexer->getClasstree(), $parser->current_baseclass); + + } else { + + $classtree = $indexer->getClasstree(); + $base = $parser->current_baseclass; + $indexExporter->exportClasstree($classtree, $base); + + } + + } + + $this->outl("... parsing modules."); + while ($modulegroup = $parser->getModulegroup()) { + + $moduleAnalyser->setModulegroup( $modulegroup ); + $moduleAnalyser->analyse(); + + while ($module = $moduleAnalyser->getModule()) { + $indexer->addModule($module); + $moduleExporter->export($module); + } + + if (floor(phpversion()) > 3) { + + $indexExporter->exportModulegroup($indexer->getModulegroup()); + + } else { + + $modulegroup = $indexer->getModulegroup(); + $indexExporter->exportModulegroup($modulegroup); + + } + + } + + $this->outl("... writing packagelist."); + if (floor(phpversion()) > 3) { + + $indexExporter->exportPackagelist($indexer->getPackages()); + $indexExporter->exportElementlist($indexer->getElementlist()); + + } else { + + $packages = $indexer->getPackages(); + $indexExporter->exportPackagelist($packages); + $elements = $indexer->getElementlist(); + $indexExporter->exportElementlist($elements); + + } + + $warningExporter->export($parser->warn->getWarnings(), "parser"); + $warningExporter->export($moduleAnalyser->warn->getWarnings(), "moduleanalyser"); + $warningExporter->export($classAnalyser->warn->getWarnings(), "classanalyser"); + + $this->outl("Parser finished."); + return true; + } // end func parse + + /** + * Renders the PHPDoc XML files as HTML files + * + * @param string Targetformat, currently only "html" is available. + * @param string Target directory for the html files + * @param string Directory with the html templates + * @return bool $ok + * @throws PhpdocError + * @access public + */ + function render($type = "html", $target = "", $template = "") { + + $this->outl("Starting to render..."); + $target = ("" == $target) ? $this->target : $this->getCheckedDirname($target); + $template = ("" == $template) ? $this->templateRoot : $this->getCheckedDirname($template); + + switch(strtolower($type)) { + + case "html": + default: + $renderer = new PhpdocHTMLRendererManager($target, $template, $this->application, $this->targetFileSuffix); + break; + } + + $fileHandler = new PhpdocFileHandler; + $files = $fileHandler->getFilesInDirectory($target, "xml"); + $len = strlen($target); + + $tpl = new IntegratedTemplate($this->templateRoot); + $tpl->loadTemplateFile("xmlfiles.html"); + $tpl->setCurrentBlock("file_loop"); + + // Do not change the file prefixes! + reset($files); + while (list($k, $file) = each($files)) { + + $tpl->setVariable("FILE", substr($file, $len)); + $tpl->parseCurrentBlock(); + + if ("class_" == substr($file, $len, 6)) { + + $renderer->render(substr($file, $len), "class"); + + } else if ("module_" == substr($file, $len, 7)) { + + $renderer->render(substr($file, $len), "module"); + + } else if ("classtree_" == substr($file, $len, 10)) { + + $renderer->render(substr($file, $len), "classtree"); + + } else if ("modulegroup_" == substr($file, $len, 12)) { + + $renderer->render(substr($file, $len), "modulegroup"); + + } else if ("warnings_" == substr($file, $len, 9)) { + + $renderer->render(substr($file, $len), "warning"); + + } + + } + + $renderer->finish(); + $fileHandler->createFile($target."phpdoc_xmlfiles".$this->targetFileSuffix, $tpl->get()); + + $this->outl($this->finishInstructions); + return true; + } // end func render + +} // end class Phpdoc ?> Index: php4/pear/PHPDoc/core/PhpdocSetupHandler.php diff -u php4/pear/PHPDoc/core/PhpdocSetupHandler.php:1.3 php4/pear/PHPDoc/core/PhpdocSetupHandler.php:1.4 --- php4/pear/PHPDoc/core/PhpdocSetupHandler.php:1.3 Mon Oct 16 04:13:42 2000 +++ php4/pear/PHPDoc/core/PhpdocSetupHandler.php Sat Dec 2 16:37:58 2000 @@ -110,17 +110,17 @@ * @see targetFileSuffix * @author Thomas Weinert <subjective@subjective.de> */ - - function setTargetFileSuffix($suffix) { - if (!( ereg("^\.",$suffix) || ($suffix == "") )) { - $this->err[] = new PhpdocError("The file extension contains no point at begin.", __FILE__, __LINE__); - return false; - } - $this->targetFileSuffix = $suffix; - return true; - } - - /** + function setTargetFileSuffix($suffix) { + if ("" != $suffix && "." != $suffix[0]) { + $this->err[] = new PhpdocError("Make sure that the file extension starts with a dot.", __FILE__, __LINE__); + return false; + } + + $this->targetFileSuffix = $suffix; + return true; + } + + /** * Suffix of all source code files in the application * By default only files with the suffix ".php" are recognized as * php source code files and parsed. If you used other @@ -134,7 +134,7 @@ * @see sourceFileSuffix */ function setSourceFileSuffix($suffix) { - if ( (!is_array($suffix) && ""==$suffix) || (is_array($suffix) && 0==count($suffix)) ) { + if ( (!is_array($suffix) && "" == $suffix) || (is_array($suffix) && 0 == count($suffix)) ) { $this->err[] = new PhpdocError("No suffix specified.", __FILE__, __LINE__); return false; } @@ -154,7 +154,7 @@ * @access public */ function setTarget($target) { - if (""==$target) { + if ("" == $target) { $this->err[] = new PhpdocError("No target specified.", __FILE__, __LINE__); return false; } @@ -178,7 +178,7 @@ * @access private * @return array $errors */ - function checkStatus($errors="") { + function checkStatus($errors = "") { if (!is_array($errors)) $errors = array(); /* @@ -208,8 +208,8 @@ */ function getCheckedDirname($dirname) { - if (""!=$dirname && "/"!=substr($dirname, -1)) - $dirname.="/"; + if ("" != $dirname && "/" != substr($dirname, -1)) + $dirname .= "/"; return $dirname; } // end func getCheckedDirname Index: php4/pear/PHPDoc/parser/PhpdocParserCore.php diff -u php4/pear/PHPDoc/parser/PhpdocParserCore.php:1.1 php4/pear/PHPDoc/parser/PhpdocParserCore.php:1.2 --- php4/pear/PHPDoc/parser/PhpdocParserCore.php:1.1 Sun Oct 8 03:03:19 2000 +++ php4/pear/PHPDoc/parser/PhpdocParserCore.php Sat Dec 2 16:37:59 2000 @@ -456,22 +456,30 @@ */ function getDescription($phpdoc) { + // find the position of the first doc tag $positions = $this->getTagPos($phpdoc); + + if (0 == count($positions)) + $desc = trim($phpdoc); // no doc tags + else + $desc = trim(substr($phpdoc, 0, $positions[0]["pos"])); // strip tags + + $lines = split($this->PHP_BASE["break"], $desc); + + if (1 == count($lines) || "" == $desc) { - if (0==count($positions)) { - $desc = trim($phpdoc); - $description = array ($desc, $desc); + // only a short description but no long description - or even none of both + $description = array ($desc, ""); + } else { - $desc = trim(substr($phpdoc, 0, $positions[0]["pos"])); - $lines = split($this->PHP_BASE["break"], $phpdoc); + $sdesc = trim($lines[0]); + unset($lines[0]); + + $description = array ( $sdesc, implode("", $lines) ); - if (1==count($lines) || ""==$desc) - $description = array ($desc, $desc); - else - $description = array ( trim($lines[0]), $desc ); } - + return $description; } // end func getDescription