home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 August / PCWorld_2001-08_cd.bin / Komunikace / phptriad / phptriadsetup2-11.exe / php / pear / PHPDoc / analyser / PhpdocClassAnalyser.php < prev    next >
PHP Script  |  2001-02-18  |  23KB  |  553 lines
  1. <?php
  2. /**
  3. * Analyses a class.
  4. * 
  5. * @version    $Id: PhpdocClassAnalyser.php,v 1.5 2001/02/18 15:19:15 uw Exp $
  6. */
  7. class PhpdocClassAnalyser extends PhpdocAnalyser {
  8.  
  9.     /**
  10.     * Class data.
  11.     *
  12.     * @var  array
  13.     */
  14.     var $classes = array();
  15.     
  16.     /**
  17.     * Name of the baseclass of the given classes.
  18.     *
  19.     * @var  string    
  20.     */
  21.     var $baseclass = "";
  22.     
  23.     /**
  24.     * Ordered list of all classes.
  25.     *
  26.     * @var  array
  27.     */ 
  28.     var $classlist = array();
  29.     
  30.     /**
  31.     * List of not inherited elements.
  32.     *
  33.     * @var  array
  34.     */
  35.     var $notinherited = array(
  36.                                 "class"    => array(
  37.                                                     "name"          => true,
  38.                                                     "extends"       => true,
  39.                                                     "undoc"         => true,
  40.                                                     "variables"     => true,
  41.                                                     "functions"     => true,
  42.                                                     "consts"        => true,
  43.                                                     "uses"          => true,
  44.                                                     "filename"      => true,
  45.                                                     "subclasses"    => true,
  46.                                                     "path"          => true,
  47.                                                     "baseclass"     => true,
  48.                                                     "abstract"      => true
  49.                                                 ),
  50.                                                                 
  51.                                 "functions"    => array(
  52.                                                         "name"      => true,
  53.                                                         "undoc"     => true,
  54.                                                         "inherited" => true,
  55.                                                         "overrides" => true,
  56.                                                         "abstract"  => true
  57.                                                     ),
  58.                                                                         
  59.                                 "variables"    => array(
  60.                                                         "name"      => true,
  61.                                                         "undoc"     => true,
  62.                                                         "inherited" => true,
  63.                                                         "overrides" => true,
  64.                                                         "abstract"  => true
  65.                                                     ),    
  66.                                                                         
  67.                                 "uses"            => array(
  68.                                                             "name"      => true,
  69.                                                             "undoc"     => true,
  70.                                                             "inherited" => true,
  71.                                                             "overrides" => true
  72.                                                         ),                                                                                                                                                                                                                                
  73.                                 
  74.                                 "consts"    => array(
  75.                                                     "name"      => true,
  76.                                                     "undoc"     => true,
  77.                                                     "inherited" => true,
  78.                                                     "overrides" => true
  79.                                                 )                                                                                                                        
  80.                         );
  81.                                                     
  82.  
  83.     /**
  84.     * Puuuh - findUndocumented() needs this.
  85.     *
  86.     * @var  array
  87.     * @see  findUndocumented()
  88.     */                                                        
  89.     var $undocumentedFields = array(
  90.                                     "functions"    => "function",
  91.                                     "variables"    => "variable",
  92.                                     "uses"            => "included file",
  93.                                     "consts"        => "constant"
  94.                             );
  95.  
  96.     /**
  97.     * Sets the class data and the name of the baseclass.
  98.     *
  99.     * @param    array   Raw class data from the parser
  100.     * @param    string  Name of the baseclass of the given classes
  101.     * @access   public
  102.     */                                                        
  103.     function setClasses($classes, $baseclass) {
  104.         
  105.         $this->classes = $classes;
  106.         $this->baseclass = $baseclass;
  107.         
  108.     } // end func setClasses
  109.                                                     
  110.     function analyse() {
  111.         
  112.         $this->flag_get = false;
  113.  
  114.         $this->updateAccessReturn();
  115.         $this->updateBrothersSisters();
  116.         $this->checkSee();
  117.         
  118.         $this->classlist = array();
  119.         
  120.         $this->buildBottomUpClasslist($this->baseclass);
  121.         
  122.     } // end func analyse
  123.  
  124.     /**
  125.     * Returns an analysed class or false if there're no classes any more.
  126.     *
  127.     * @return   mixed   False if there no classes anymore, otherwise an array with 
  128.     *                   the data of the class.
  129.     * @accesss  public
  130.     */    
  131.     function getClass() {
  132.     
  133.         if (!$this->flag_get) {
  134.             reset($this->classlist);
  135.             $this->flag_get = true;
  136.         }
  137.         if (list($k, $classname) = each($this->classlist)) {
  138.  
  139.             if (isset($this->classes[$classname]["path"]))
  140.                 $this->inheritClassElements($classname);    
  141.             
  142.             $this->checkFunctionArgs($classname);
  143.             $this->findUndocumented($classname);
  144.             
  145.             $class = $this->classes[$classname];
  146.             unset($this->classes[$classname]);
  147.             return $class;
  148.             
  149.         } else {
  150.         
  151.             return false;
  152.             
  153.         }
  154.     } // end func getClass
  155.  
  156.     /**
  157.     * Looks for undocumented elements in a certain class
  158.     * 
  159.     * @param    string  Classname
  160.     */
  161.     function findUndocumented($classname) {
  162.         
  163.         $file = $this->classes["filename"];
  164.         if ($this->classes["undoc"])
  165.             $this->warn->addDocWarning($file, "class", $name, "The class is not documented.", "missing");
  166.             
  167.         reset($this->undocumentedFields);
  168.         while (list($index, $eltype) = each($this->undocumentedFields)) {
  169.             if (!isset($this->classes[$index]))
  170.                 continue;
  171.                 
  172.             reset($this->classes[$index]);
  173.             while (list($elname, $data) = each($this->classes[$index]))
  174.                 if (isset($data["undoc"]) && $data["undoc"])
  175.                     $this->warn->addDocWarning($file, $eltype, $elname, "Undocumented element.", "missing");
  176.                     
  177.         }
  178.         
  179.     } // end func findUndocumented
  180.     
  181.     /**
  182.     * Checks the function documentation of a certain class.
  183.     *
  184.     * @param    string  Classname
  185.     */
  186.     function checkFunctionArgs($classname) {
  187.  
  188.         if (!isset($this->classes[$classname]["functions"]))
  189.             return;
  190.                 
  191.         $file = $this->classes[$classname]["filename"];
  192.             
  193.         reset($this->classes[$classname]["functions"]);
  194.         while (list($fname, $function) = each($this->classes[$classname]["functions"])) {
  195.  
  196.             $inherited = isset($function["paraminherited"]);            
  197.             $this->classes[$classname]["functions"][$fname]["params"] = $this->checkArgDocs($function["args"], $function["params"], $fname, $file, $inherited);
  198.             unset($this->classes[$classname]["functions"][$fname]["args"]);
  199.  
  200.             if ($inherited)
  201.                 unset($this->classes[$classname]["functions"][$fname]["paraminherited"]);
  202.                 
  203.         }
  204.     } // end func checkFunctionArgs
  205.     
  206.     /**
  207.     * Builds an internal list of all classes.
  208.     * 
  209.     * The analyser needs an ordered list of all classes
  210.     * to inherit information effective.
  211.     * 
  212.     * @param    string      Name of the class that starts the recursive build process. 
  213.     * @see      $classlist
  214.     */
  215.     function buildBottomUpClasslist($classname) {
  216.         
  217.         if (isset($this->classes[$classname]["subclasses"])) {
  218.             
  219.             reset($this->classes[$classname]["subclasses"]);
  220.             while (list($subclass, $v) = each($this->classes[$classname]["subclasses"]))
  221.                 $this->buildBottomUpClasslist($subclass);
  222.             
  223.             $this->classlist[] = $classname;
  224.             
  225.         } else {
  226.          
  227.              $this->classlist[] = $classname;
  228.         
  229.         }
  230.     } // end func buildBottomUpClasslist
  231.  
  232.     /**
  233.     * Adds inherited elements to a class.
  234.     * 
  235.     * @param    string  Classname
  236.     * @return   boolean $ok
  237.     * @see      $classes, $notinherited, addInheritedElements()
  238.     */    
  239.     function inheritClassElements($classname) {
  240.         
  241.         if (!isset($this->classes[$classname]["path"]))
  242.             return false;
  243.  
  244.         $undoc = $this->classes[$classname]["undoc"];
  245.                 
  246.         $path = $this->classes[$classname]["path"];
  247.         reset($path);
  248.         while (list($k, $parentclass) = each($path)) {
  249.  
  250.             $this->addInheritedElements($classname, $parentclass, "functions");
  251.             $this->addInheritedElements($classname, $parentclass, "variables");
  252.             $this->addInheritedElements($classname, $parentclass, "consts");
  253.             $this->addInheritedElements($classname, $parentclass, "uses");
  254.             
  255.             reset($this->classes[$parentclass]);
  256.             while (list($field, $value) = each($this->classes[$parentclass])) 
  257.                 if (!isset($this->notinherited["class"][$field]) && !isset($this->classes[$classname][$field]))
  258.                     $this->classes[$classname][$field] = $value;
  259.             
  260.             if ($undoc && !$this->classes[$parentclass]["undoc"]) {
  261.                 $this->classes[$classname]["docinherited"] = true;
  262.                 $this->classes[$classname]["undoc"] = false;
  263.                 $undoc = false;
  264.             }
  265.             
  266.         }    
  267.         
  268.         return true;
  269.     } // end func inheritClassElements
  270.     
  271.     /**
  272.     * Adds inherited functions, variables, constants or included files to a class.
  273.     *  
  274.     * @param    string  Name of the class that inherits the informations.
  275.     * @param    string  Name of the parentclass
  276.     * @param    string  Type of elements inherited: "functions", "variables", "uses", "consts"
  277.     * @return   boolean $ok
  278.     * @see      $classes, $notinherited, isUndocumented()
  279.     */
  280.     function addInheritedElements($classname, $parentclass, $type) {
  281.     
  282.         if (!isset($this->classes[$parentclass][$type]))
  283.             return false;
  284.             
  285.         reset($this->classes[$parentclass][$type]);
  286.         while (list($elementname, $data) = each($this->classes[$parentclass][$type])) {
  287.             
  288.             if (!isset($this->classes[$classname][$type][$elementname])) {
  289.  
  290.                 $this->classes[$classname]["inherited"][$type][$parentclass][$elementname] = true;            
  291.  
  292.             } else {
  293.         
  294.                 $this->classes[$classname][$type][$elementname]["overrides"] = $parentclass;
  295.                 $this->classes[$classname][$type][$elementname]["undoc"] = $this->isUndocumented($parentclass, $type, $elementname);
  296.                 $this->classes[$classname]["overrides"][$type][$parentclass][$elementname] = true;
  297.                 
  298.                 reset($data);
  299.                 while (list($field, $value)=each($data)) {
  300.                 
  301.                     if (!isset($this->classes[$classname][$type][$elementname][$field]) && !isset($this->notinherited[$type][$field])) {
  302.                         $this->classes[$classname][$type][$elementname][$field] = $value;
  303.                         if ("params" == $field && "functions" == $type) $this->classes[$classname][$type][$elementname]["paraminherited"] = true;
  304.                     }
  305.                         
  306.                 }
  307.             }
  308.             
  309.         }
  310.         
  311.         return true;
  312.     } // end func addInheritedElements
  313.  
  314.     /**
  315.     * Returns true if the requested element is undocumented and false if it's documented.
  316.     *
  317.     * The function checks if the element might inherit documentation
  318.     * from any parentclass. 
  319.     *
  320.     * @param    string  Name of the class of the element
  321.     * @param    string  Element type: functions, variables, uses, consts.
  322.     * @param    string  Element name
  323.     * @return   boolean $ok
  324.     */    
  325.     function isUndocumented($classname, $type, $elementname) {
  326.  
  327.         if ( !isset($this->classes[$classname][$type][$elementname]) || $this->classes[$classname][$type][$elementname]["undoc"] || !isset($this->classes[$classname]["path"]) ) 
  328.             return true;
  329.         
  330.         $path = $this->classes[$classname]["path"];
  331.         while (list($k, $parentclass) = each($path))
  332.             if ($this->isUndocumented($parentclass, $type, $elementname))
  333.                 return true;
  334.         
  335.         return false;
  336.     } // end func isUndocumented
  337.     
  338.     function updateBrothersSisters() {
  339.         
  340.         reset($this->classes);
  341.         while (list($classname, $data) = each($this->classes)) {
  342.             $this->updateBrotherSisterElements($classname, "functions");
  343.             $this->updateBrotherSisterElements($classname, "variables");
  344.         }    
  345.         
  346.     } // end func updateBrothersSisters
  347.     
  348.     /**
  349.     * @param    string  Name of the class to update
  350.     * @param    string  Elementtype: functions, variables, ...
  351.     * @return   boolean
  352.     */
  353.     function updateBrotherSisterElements($classname, $type) {
  354.         
  355.         if (!isset($this->classes[$classname][$type])) 
  356.             return false;
  357.             
  358.         reset($this->classes[$classname][$type]);
  359.         while (list($elementname, $data) = each($this->classes[$classname][$type])) {
  360.             
  361.             if (isset($data["brother"])) {
  362.  
  363.                 $name = ( "functions" == $type ) ? substr($data["brother"], 0, -2) : substr($data["brother"], 1);
  364.                 $name = strtolower($name);
  365.  
  366.                 if (!isset($this->classes[$classname][$type][$name])) {
  367.                 
  368.                     $this->warn->addDocWarning($this->classes[$classname]["filename"], $type, $elementname, "Brother '$name' is unknown. Tags gets ignored.", "mismatch");
  369.                     unset($this->classes[$classname][$type][$elementname]["brother"]);
  370.                     
  371.                 } else {
  372.                 
  373.                     $this->classes[$classname][$type][$elementname]["brother"] = $name;
  374.                     $this->classes[$classname][$type][$elementname] = $this->copyBrotherSisterFields($this->classes[$classname][$type][$elementname], $this->classes[$classname][$type][$name]);
  375.  
  376.                 }
  377.  
  378.             }
  379.             
  380.         }
  381.         
  382.     } // end func updateBrotherSisterElements
  383.     
  384.     function updateAccessReturn() {
  385.         
  386.         reset($this->classes);
  387.         while (list($classname, $data) = each($this->classes)) {
  388.             
  389.             if (!isset($data["access"]))
  390.                 $this->classes[$classname]["access"] = "private";
  391.                 
  392.             $this->updateAccessReturnElements($classname, "functions");
  393.             $this->updateAccessElements($classname, "variables");
  394.             $this->updateAccessElements($classname, "consts");
  395.             
  396.         }
  397.                 
  398.     } // end func updateAccessReturn
  399.     
  400.     /**
  401.     * Updates access and return for certain elements.
  402.     * 
  403.     * This function should only be used to update functions.
  404.     * Functions that have the same name as the class (constructors)
  405.     * get return void and access public. Functions without 
  406.     * access get access public and functions without return get
  407.     * return void.
  408.     * 
  409.     * @param    string  Classname
  410.     * @param    string  Element type: functions (, variables, consts, uses)
  411.     * @return   boolean $ok
  412.     * @see      updateAccessReturn()
  413.     */
  414.     function updateAccessReturnElements($classname, $type) {
  415.         
  416.         if (!isset($this->classes[$classname][$type]))
  417.             return false;
  418.  
  419.         reset($this->classes[$classname][$type]);
  420.         while (list($elementname, $data) = each($this->classes[$classname][$type])) {
  421.         
  422.             if (!isset($data["access"])) 
  423.                 $this->classes[$classname][$type][$elementname]["access"] = ("functions" == $type && strtolower($elementname) == strtolower($classname)) ? "public" : "private";
  424.                 
  425.             if (!isset($data["return"]))
  426.                 $this->classes[$classname][$type][$elementname]["return"] = "void";
  427.             else 
  428.                 if ("functions" == $type && $elementname == $classname) {
  429.                     $this->warn->addDocWarning($this->classes[$classname]["filename"], "functions", $elementname, "The constructor can't have a return value. @return gets ignored.", "mismatch");
  430.                     $this->classes[$classname]["functions"][$elementname]["return"] = "void";
  431.                 }
  432.                 
  433.         }
  434.                 
  435.     } // end func updateAccessReturnElements
  436.     
  437.     /**
  438.     * Updates access tags.
  439.     *
  440.     * @param    string  Classname
  441.     * @param    string  Element type: functions, variables, consts (, uses)
  442.     * @see      updateAccessReturnElements()
  443.     */
  444.     function updateAccessElements($classname, $type) {
  445.         
  446.         if (!isset($this->classes[$classname][$type]))
  447.             return false;
  448.             
  449.         reset($this->classes[$classname][$type]);
  450.         while (list($elementname, $data) = each($this->classes[$classname][$type])) {
  451.             
  452.             if (!isset($data["access"])) 
  453.                 $this->classes[$classname][$type][$elementname]["access"] = ("functions" == $type && $elementname == $classname) ? "public" : "private";
  454.         
  455.         }
  456.         
  457.     } // end func updateAccessElements
  458.     
  459.     function checkSee() {
  460.         
  461.         reset($this->classes);
  462.         while (list($classname, $class) = each($this->classes)) {
  463.         
  464.             $this->buildElementlist($classname);
  465.             
  466.             if (isset($class["functions"])) 
  467.                 $this->checkSeeElements($class["functions"], $classname, "functions");
  468.                 
  469.             if (isset($class["variables"]))
  470.                 $this->checkSeeElements($class["variables"], $classname, "variables");
  471.             
  472.             if (isset($class["consts"])) 
  473.                 $this->checkSeeElements($class["consts"], $classname, "consts");
  474.                 
  475.             if (isset($class["uses"]))
  476.                 $this->checkSeeElements($class["uses"], $classname, "uses");
  477.             
  478.         }
  479.         
  480.     } // end func checkSee
  481.  
  482.     /**
  483.     * Checks see references in the given element array (functions, variables...)
  484.     *
  485.     * References to variables and functions within the same class get checked.
  486.     * It the references element does not exist, the reference gets deleted and 
  487.     * a doc warning gets generated.
  488.     * 
  489.     * @param    array   List of functions, variables,...
  490.     * @param    string  Name of the class that contains the given elements.
  491.     * @param    string  Elementtype: functions, variables, consts, uses.
  492.     */    
  493.     function checkSeeElements($elements, $classname, $eltype) {
  494.         
  495.         reset($elements);
  496.         while (list($elname, $element) = each($elements)) {
  497.         
  498.             if (isset($element["see"])) {
  499.                 
  500.                 if (isset($element["see"]["var"])) {
  501.                     
  502.                     reset($element["see"]["var"]);
  503.                     while (list($k, $variable) = each($element["see"]["var"])) 
  504.                         if (!isset($this->elementlist["variables"][strtolower($variable["name"])])) {
  505.                             $this->warn->addDocWarning($this->classes[$classname]["filename"], "variables", $elname, "@see referrs to the variable '" . $variable["name"] . "' which is not defined in the class. Entry gets ignored.", "mismatch");
  506.                             unset($this->classes[$classname][$eltype][$elname]["see"]["var"][$k]);
  507.                         }
  508.  
  509.                 }
  510.                 
  511.                 if (isset($element["see"]["function"])) {
  512.                     
  513.                     reset($element["see"]["function"]);
  514.                     while (list($k, $function) = each($element["see"]["function"]))
  515.                         if (!isset($this->elementlist["functions"][strtolower(substr($function["name"], 0, -2))])) {
  516.                             $this->warn->addDocWarning($this->classes[$classname]["filename"], "functions", $elname, "@see referrs to the function '" . $function["name"] . "' which is not defined in the class. Entry gets ignored.", "mismatch");
  517.                             unset($this->classes[$classname][$eltype][$elname]["see"]["function"][$k]);
  518.                         }
  519.  
  520.                 }
  521.                 
  522.             }
  523.             
  524.         }    
  525.         
  526.     } // end func checkSeeElement
  527.     
  528.     /**
  529.     * Builds an array with all elements of a class and saves it to $this->elementlist.
  530.     * 
  531.     * @param    string  Name of the class to scan.
  532.     */
  533.     function buildElementlist($classname) {
  534.         
  535.         $elements = array();
  536.         $fields = array("functions", "variables", "consts", "uses");
  537.         
  538.         reset($fields);
  539.         while (list($k, $field) = each($fields)) 
  540.             if (isset($this->classes[$classname][$field])) {
  541.                 
  542.                 reset($this->classes[$classname][$field]);
  543.                 while (list($element, ) = each($this->classes[$classname][$field])) 
  544.                     $elements[$field][$element] = true;
  545.                     
  546.             }
  547.         
  548.         $this->elementlist = $elements;
  549.         
  550.     } // end func buildElementlist
  551.  
  552. } // end class PhpdocClassAnalyser
  553. ?>