phpDocumentor phpDocumentor
[ class tree: phpDocumentor ] [ index: phpDocumentor ] [ all elements ]

Source for file ProceduralPages.inc

Documentation is available at ProceduralPages.inc

  1. <?php
  2. /**
  3.  * Intermediate procedural page parsing structure.
  4.  * This structure parses defines, functions, and global variables by file,
  5.  * and then iterates over the elements to document conflicts.
  6.  * 
  7.  * phpDocumentor :: automatic documentation generator
  8.  * 
  9.  * PHP versions 4 and 5
  10.  *
  11.  * Copyright (c) 2002-2006 Gregory Beaver
  12.  * 
  13.  * LICENSE:
  14.  * 
  15.  * This library is free software; you can redistribute it
  16.  * and/or modify it under the terms of the GNU Lesser General
  17.  * Public License as published by the Free Software Foundation;
  18.  * either version 2.1 of the License, or (at your option) any
  19.  * later version.
  20.  * 
  21.  * This library is distributed in the hope that it will be useful,
  22.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  23.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  24.  * Lesser General Public License for more details.
  25.  * 
  26.  * You should have received a copy of the GNU Lesser General Public
  27.  * License along with this library; if not, write to the Free Software
  28.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  29.  *
  30.  * @package    phpDocumentor
  31.  * @author     Gregory Beaver <cellog@php.net>
  32.  * @copyright  2002-2006 Gregory Beaver
  33.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  34.  * @version    CVS: $Id: ProceduralPages.inc,v 1.4 2006/10/23 03:32:56 cellog Exp $
  35.  * @link       http://www.phpdoc.org
  36.  * @link       http://pear.php.net/PhpDocumentor
  37.  * @since      1.1
  38.  */
  39.  
  40. /**
  41.  * Intermediate procedural page parsing structure.
  42.  * This structure parses defines, functions, and global variables by file,
  43.  * and then iterates over the elements to document conflicts.
  44.  * @package phpDocumentor
  45.  * @author Greg Beaver <cellog@users.sourceforge.net>
  46.  * @since 1.1
  47.  * @version $Id: ProceduralPages.inc,v 1.4 2006/10/23 03:32:56 cellog Exp $
  48.  */
  49. {
  50.     /**
  51.      * file being parsed, used in every add function to match up elements with the file that contains them
  52.      * @see addClass(), addMethod(), addVar(), nextFile()
  53.      * @var string 
  54.      */
  55.     var $curfile;
  56.     /**
  57.      * array of all procedural pages ordered by name
  58.      * Format:
  59.      * array(name => array(fullpath => parserPage,fullpath => parserPage2 [if there are name conflicts],...))
  60.      * @var array 
  61.      */
  62.     var $pages = array();
  63.     /**
  64.      * array of all procedural pages ordered by name that have been ignored via -po or @access private or @ignore
  65.      * Format:
  66.      * array(name => array(fullpath => parserPage,fullpath => parserPage2 [if there are name conflicts],...))
  67.      * @var array 
  68.      */
  69.     var $ignorepages = array();
  70.     /**
  71.      * array of all procedural page names ordered by full path to the file
  72.      * Format:
  73.      * array(fullpath => name)
  74.      * @var array 
  75.      */
  76.     var $pathpages = array();
  77.     /**
  78.      * array of parsed includes organized by the full path of the file that contains the include.
  79.      * Format:
  80.      * array(full path => array(includename => {@link parserInclude}))
  81.      * @var array 
  82.      */
  83.     var $includesbyfile = array();
  84.     /**
  85.      * array of parsed functions organized by the full path of the file that contains the function.
  86.      * Format:
  87.      * array(full path => array(functionname => {@link parserFunction}))
  88.      * @var array 
  89.      */
  90.     var $functionsbyfile = array();
  91.     /**
  92.      * array of parsed defines organized by the full path of the file that contains the define.
  93.      * Format:
  94.      * array(full path => array(definename => {@link parserDefine}))
  95.      * @var array 
  96.      */
  97.     var $definesbyfile = array();
  98.     /**
  99.      * array of parsed global variables organized by the full path of the file that contains the global variable definition.
  100.      * Format:
  101.      * array(full path => array(globalname => {@link parserGlobal}))
  102.      * @var array 
  103.      */
  104.     var $globalsbyfile = array();
  105.     /**
  106.      * array of file names organized by functions that are in the file.
  107.      * This structure is designed to handle name conflicts.  Two files can contain functions with the same name, and this array will
  108.      * record both filenames to help control namespace errors
  109.      * Format:
  110.      * array(functionname => array(full path of file containing functionname, full path of file 2 containing functionname...)
  111.      * @var array 
  112.      */
  113.     var $functionsbynamefile = array();
  114.     /**
  115.      * array of file names organized by defines that are in the file.
  116.      * This structure is designed to handle name conflicts.  Two files can contain defines with the same name, and this array will
  117.      * record both filenames to help control namespace errors
  118.      * Format:
  119.      * array(definename => array(full path of file containing definename, full path of file 2 containing definename...)
  120.      * @var array 
  121.      */
  122.     var $definesbynamefile = array();
  123.     /**
  124.      * array of file names organized by global variables that are in the file.
  125.      * This structure is designed to handle name conflicts.  Two files can contain global variables with the same name, and this array will
  126.      * record both filenames to help control namespace errors
  127.      * Format:
  128.      * array(global variablename => array(full path of file containing global variablename, full path of file 2 containing global variablename...)
  129.      * @var array 
  130.      */
  131.     var $globalsbynamefile = array();
  132.     /**
  133.      * array of packages ordered by full path
  134.      * Format:
  135.      * array(fullpath => array(packagename,subpackagename))
  136.      * @var array 
  137.      */
  138.     var $pagepackages = array();
  139.     /**
  140.      * array of packages assigned to classes in a file, ordered by fullpath
  141.      * Format:
  142.      * array(fullpath => array(packagename => array(subpackagename => 1,subpackagename => 1,..),packagename2 =>...)
  143.      * @var array 
  144.      */
  145.     var $pageclasspackages = array();
  146.     /**
  147.      * Namespace conflicts within all documented packages of functions
  148.      * Format:
  149.      * array(functionname => array(full path, full path,...))
  150.      * @var array 
  151.      */
  152.     var $functionconflicts = array();
  153.     /**
  154.      * Namespace conflicts within all documented pages
  155.      * Format:
  156.      * array(pagename => array(fullpath, fullpath,...))
  157.      * @var array 
  158.      */
  159.     var $pageconflicts = array();
  160.     /**
  161.      * Namespace conflicts within all documented packages of functions
  162.      * Format:
  163.      * array(functionname => array(full path, full path,...))
  164.      * @var array 
  165.      */
  166.     var $defineconflicts = array();
  167.     /**
  168.      * Namespace conflicts within all documented packages of functions
  169.      * Format:
  170.      * array(functionname => array(full path, full path,...))
  171.      * @var array 
  172.      */
  173.     var $globalconflicts = array();
  174.     /** @access private
  175.      * @var array */
  176.     var $revcpbf array();
  177.     /** @access private
  178.      * @var boolean */
  179.     var $packagesetup false;
  180.  
  181.     /**
  182.      * sets up the {@link $pages} array
  183.      * @param parserPage &$element 
  184.      */
  185.     function addPage(&$element)
  186.     {
  187.         $this->curfile = $element->getPath();
  188.         $this->pages[$element->getFile()][$element->getPath()$element;
  189.         $this->pathpages[$this->curfile$element->getFile();
  190.         $this->addPagePackage($this->curfile$element->package$element->subpackage);
  191.     }
  192.     
  193.     /**
  194.      * moves a page from the {@link $pages} array to the {@link $ignorepages} array
  195.      * @param parserPage &$element 
  196.      */
  197.     function ignorePage(&$element)
  198.     {
  199.         $this->ignorepages[$element->getFile()][$element->getPath()$this->pages[$element->getFile()][$element->getPath()];
  200.         unset($this->pages[$element->getFile()][$element->getPath()]);
  201.     }
  202.  
  203.     function getPathInfo($path,&$c)
  204.     {
  205.         $path str_replace('/',SMART_PATH_DELIMITER,$path);
  206.         $info array();
  207.         if (!isset($this->pathpages[$path])) return false;
  208.         $p $this->pages[$this->pathpages[$path]][$path];
  209.         // fixes [ 1391432 ] Too many underscores in include links.
  210.         $p->name $p->origName;
  211.         $p->name $c->getPageName($p);
  212.         $info['package'$p->package;
  213.         $info['subpackage'$p->subpackage;
  214.         $info['name'$p->getFile();
  215.         $info['source_loc'$p->getSourceLocation($c);
  216.         $x new pageLink;
  217.         $x->addLink($p->path,$p->name,$p->file,$p->package$p->subpackage);
  218.         $info['docs'$c->returnSee($x);
  219.         $p->name $p->origName;
  220.         return $info;
  221.     }
  222.     
  223.     /**
  224.      * Change a page's name from its file to alias $name
  225.      *
  226.      * This function is used to handle a @name tag in a page-level DocBlock
  227.      * @param string $name 
  228.      */
  229.     function setName($name)
  230.     {
  231.         $this->pages[$name][$this->curfile$this->pages[$this->pathpages[$this->curfile]][$this->curfile];
  232.         $this->pages[$name][$this->curfile]->file $name;
  233.         unset($this->pages[$this->pathpages[$this->curfile]][$this->curfile]);
  234.         $this->pathpages[$this->curfile$name;
  235.     }
  236.     
  237.     /**
  238.      * Changes the package of the page represented by $path
  239.      *
  240.      * changes package in both the {@link $pages} array and the {@link pagepackages} array
  241.      * @param string $path full path
  242.      * @param string $package 
  243.      * @param string $subpackage 
  244.      */
  245.     function addPagePackage($path,$package,$subpackage)
  246.     {
  247.         $this->pages[$this->pathpages[$path]][$path]->package $package;
  248.         $this->pages[$this->pathpages[$path]][$path]->subpackage $subpackage;
  249.         $this->pagepackages[$patharray($package$subpackage);
  250.         if (isset($this->includesbyfile[$path]))
  251.         {
  252.             foreach($this->includesbyfile[$pathas $i => $el)
  253.             {
  254.                 $el->package $package;
  255.                 $el->subpackage $subpackage;
  256.                 $this->includesbyfile[$path][$i$el;
  257.             }
  258.         }
  259.         if (isset($this->functionsbyfile[$path]))
  260.         {
  261.             foreach($this->functionsbyfile[$pathas $i => $el)
  262.             {
  263.                 $el->package $package;
  264.                 $el->subpackage $subpackage;
  265.                 $this->functionsbyfile[$path][$i$el;
  266.             }
  267.         }
  268.         if (isset($this->definesbyfile[$path]))
  269.         {
  270.             foreach($this->definesbyfile[$pathas $i => $el)
  271.             {
  272.                 $el->package $package;
  273.                 $el->subpackage $subpackage;
  274.                 $this->definesbyfile[$path][$i$el;
  275.             }
  276.         }
  277.         if (isset($this->globalsbyfile[$path]))
  278.         {
  279.             foreach($this->globalsbyfile[$pathas $i => $el)
  280.             {
  281.                 $el->package $package;
  282.                 $el->subpackage $subpackage;
  283.                 $this->globalsbyfile[$path][$i$el;
  284.             }
  285.         }
  286.     }
  287.  
  288.     /**
  289.      * sets up the {@link $includesbyfile} array using {@link $curfile}
  290.      * @param parserInclude &$element 
  291.      */
  292.     function addInclude(&$element)
  293.     {
  294.         $this->includesbyfile[$this->curfile][$element;
  295.     }
  296.  
  297.     /**
  298.      * sets up the {@link $functionsbyfile} array using {@link $curfile}
  299.      * @param parserFunction &$element 
  300.      */
  301.     function addFunction(&$element)
  302.     {
  303.         if (isset($this->functionsbyfile[$this->curfile]))
  304.         {
  305.             foreach($this->functionsbyfile[$this->curfileas $i => $function)
  306.             {
  307.                 if ($function->getName(== $element->getName())
  308.                 {
  309.                     addWarning(PDERROR_ELEMENT_IGNORED,'function',$element->getName(),$this->curfile);
  310.                     return;
  311.                 }
  312.             }
  313.         }
  314.         $this->functionsbyfile[$this->curfile][$element;
  315.         $this->functionsbynamefile[$element->getName()][$this->curfile;
  316.     }
  317.  
  318.     /**
  319.      * sets up the {@link $globalsbyfile} array using {@link $curfile}
  320.      * @param parserGlobal &$element 
  321.      */
  322.     function addGlobal(&$element)
  323.     {
  324.         if (isset($this->globalsbyfile[$this->curfile]))
  325.         {
  326.             foreach($this->globalsbyfile[$this->curfileas $i => $global)
  327.             {
  328.                 if ($global->getName(== $element->getName())
  329.                 {
  330.                     addWarning(PDERROR_ELEMENT_IGNORED,'global variable',$element->getName(),$this->curfile);
  331.                     return;
  332.                 }
  333.             }
  334.         }
  335.         $this->globalsbyfile[$this->curfile][$element;
  336.         $this->globalsbynamefile[$element->getName()][$this->curfile;
  337.     }
  338.  
  339.     /**
  340.      * sets up the {@link $definesbyfile} array using {@link $curfile}
  341.      * @param parserDefine &$element 
  342.      */
  343.     function addDefine(&$element)
  344.     {
  345.         if (isset($this->definesbyfile[$this->curfile]))
  346.         {
  347.             foreach($this->definesbyfile[$this->curfileas $i => $define)
  348.             {
  349.                 if ($define->getName(== $element->getName())
  350.                 {
  351.                     addWarning(PDERROR_ELEMENT_IGNORED,'define',$element->getName(),$this->curfile);
  352.                     return;
  353.                 }
  354.             }
  355.         }
  356.         $this->definesbyfile[$this->curfile][$element;
  357.         $this->definesbynamefile[$element->getName()][$this->curfile;
  358.     }
  359.     
  360.     /**
  361.      * Used to align an element with the package of its parent page prior to Conversion.
  362.      * @param parserElement &$element 
  363.      */
  364.     function replaceElement(&$element)
  365.     {
  366.         if ($element->type == 'define')
  367.         {
  368.             foreach($this->definesbyfile[$element->getPath()as $i => $el)
  369.             {
  370.                 if ($el->getName(== $element->getName())
  371.                 {
  372.                     $this->definesbyfile[$element->getPath()][$i&$element;
  373.                 }
  374.             }
  375.         elseif ($element->type == 'global')
  376.         {
  377.             foreach($this->globalsbyfile[$element->getPath()as $i => $el)
  378.             {
  379.                 if ($el->getName(== $element->getName())
  380.                 {
  381.                     $this->globalsbyfile[$element->getPath()][$i&$element;
  382.                 }
  383.             }
  384.         elseif ($element->type == 'include')
  385.         {
  386.             foreach($this->includesbyfile[$element->getPath()as $i => $el)
  387.             {
  388.                 if ($el->getName(== $element->getName())
  389.                 {
  390.                     $this->includesbyfile[$element->getPath()][$i&$element;
  391.                 }
  392.             }
  393.         elseif ($element->type == 'function')
  394.         {
  395.             foreach($this->functionsbyfile[$element->getPath()as $i => $el)
  396.             {
  397.                 if ($el->getName(== $element->getName())
  398.                 {
  399.                     $this->functionsbyfile[$element->getPath()][$i&$element;
  400.                 }
  401.             }
  402.         }
  403.     }
  404.  
  405.     /**
  406.      * adds a package from a class to the current file
  407.      * @param string $file    full path to the file that contains the class
  408.      * @param string $package package name
  409.      */
  410.     function addClassPackageToFile($file,$package,$subpackage)
  411.     {
  412.         // don't care about default
  413. //        if ($package == $GLOBALS['phpDocumentor_DefaultPackageName'])
  414. //        $this->revcpbf[$file][$package][$subpackage] = 1;
  415.         if (!isset($this->revcpbf[$file][$package][$subpackage]))
  416.         {
  417.             $this->pageclasspackages[$file][$package][$subpackage1;
  418.         }
  419.         $this->revcpbf[$file][$package][$subpackage1;
  420.     }
  421.     
  422.     /**
  423.      * if there is one class package in a file, the parent path inherits the package if its package is default.
  424.      * helps with -po to avoid dumb bugs
  425.      */
  426.     function setupPagePackages()
  427.     {
  428.         if ($this->packagesetupreturn;
  429.         foreach($this->pageclasspackages as $fullpath => $packages)
  430.         {
  431.             if (isset($this->pagepackages[$fullpath]))
  432.             {
  433.                 if ($this->pagepackages[$fullpath][0== $GLOBALS['phpDocumentor_DefaultPackageName'])
  434.                 {
  435.                     if (count($packages== 1)
  436.                     {
  437.                         list($package,$subpackageeach($packages);
  438.                         if (count($subpackage== 1list($subpackage,each($subpackage);
  439.                         else $subpackage '';
  440.                         $this->addPagePackage($fullpath,$package,$subpackage);
  441.                     }
  442.                 }
  443.             }
  444.         }
  445.         $this->packagesetup true;
  446.     }
  447.     
  448.     /**
  449.      * extracts function, define, and global variable name conflicts within the same package and between different
  450.      * packages.  No two elements with the same name are allowed in the same package, to keep automatic linking
  451.      * possible.
  452.      * @access private
  453.      */
  454.     function setupConflicts(&$render)
  455.     {
  456.         
  457.         foreach($this->functionsbynamefile as $function => $paths)
  458.         {
  459.             if (count($paths1)
  460.             //conflict
  461.                 $package array();
  462.                 foreach($paths as $path)
  463.                 {
  464.                     // create a list of conflicting functions in each package
  465.                     $package[$this->pagepackages[$path][0]][$path;
  466.                 }
  467.                 foreach($package as $pathpackages)
  468.                 {
  469.                     // if at least 2 functions exist in the same package, delete all but the first one and add warnings
  470.                     if (count($pathpackages1)
  471.                     {
  472.                         for($i=1$i count($pathpackages)$i++)
  473.                         {
  474.                             addWarning(PDERROR_ELEMENT_IGNORED,'function',$function,$pathpackages[$i]);
  475.                             foreach($this->functionsbyfile[$pathpackages[$i]] as $j => $blah)
  476.                             {
  477.                                 if ($this->functionsbyfile[$pathpackages[$i]][$j]->getName(== $function)
  478.                                 unset($this->functionsbyfile[$pathpackages[$i]][$j]);
  479.                             }
  480.                             $oth array_flip($paths);
  481.                             unset($paths[$oth[$pathpackages[$i]]]);
  482.                         }
  483.                     }
  484.                 }
  485.                 $this->functionconflicts[$function$paths;
  486.             }
  487.         }
  488.  
  489.         foreach($this->definesbynamefile as $define => $paths)
  490.         {
  491.             if (count($paths1)
  492.             //conflict
  493.                 $package array();
  494.                 foreach($paths as $path)
  495.                 {
  496.                     // create a list of conflicting functions in each package
  497.                     $package[$this->pagepackages[$path][0]][$path;
  498.                 }
  499.                 foreach($package as $pathpackages)
  500.                 {
  501.                     // if at least 2 functions exist in the same package, delete all but the first one and add warnings
  502.                     if (count($pathpackages1)
  503.                     {
  504.                         for($i=1$i count($pathpackages)$i++)
  505.                         {
  506.                             addWarning(PDERROR_ELEMENT_IGNORED,'define',$define,$pathpackages[$i]);
  507.                             foreach($this->definesbyfile[$pathpackages[$i]] as $j => $blah)
  508.                             {
  509.                                 if ($this->definesbyfile[$pathpackages[$i]][$j]->getName(== $define)
  510.                                 unset($this->definesbyfile[$pathpackages[$i]][$j]);
  511.                             }
  512.                             $oth array_flip($paths);
  513.                             unset($paths[$oth[$pathpackages[$i]]]);
  514.                         }
  515.                     }
  516.                 }
  517.                 $this->defineconflicts[$define$paths;
  518.             }
  519.         }
  520.  
  521.         foreach($this->globalsbynamefile as $global => $paths)
  522.         {
  523.             if (count($paths1)
  524.             //conflict
  525.                 $package array();
  526.                 foreach($paths as $path)
  527.                 {
  528.                     // create a list of conflicting functions in each package
  529.                     $package[$this->pagepackages[$path][0]][$path;
  530.                 }
  531.                 foreach($package as $pathpackages)
  532.                 {
  533.                     // if at least 2 functions exist in the same package, delete all but the first one and add warnings
  534.                     if (count($pathpackages1)
  535.                     {
  536.                         for($i=1$i count($pathpackages)$i++)
  537.                         {
  538.                             addWarning(PDERROR_ELEMENT_IGNORED,'global variable',$global,$pathpackages[$i]);
  539.                             foreach($this->globalsbyfile[$pathpackages[$i]] as $j => $blah)
  540.                             {
  541.                                 if ($this->globalsbyfile[$pathpackages[$i]][$j]->getName(== $global)
  542.                                 unset($this->globalsbyfile[$pathpackages[$i]][$j]);
  543.                             }
  544.                             $oth array_flip($paths);
  545.                             unset($paths[$oth[$pathpackages[$i]]]);
  546.                         }
  547.                     }
  548.                 }
  549.                 $this->globalconflicts[$global$paths;
  550.             }
  551.         }
  552.         
  553.         foreach($this->pages as $name => $pages)
  554.         {
  555.             if (count($pages1)
  556.             // possible conflict
  557.                 
  558.             }
  559.         }
  560.     }
  561.     
  562.     /**
  563.      * called by {@link parserFunction::getConflicts()} to get inter-package conflicts, should not be called directly
  564.      * @access private
  565.      * @return array Format: (package => {@link parserFunction} of conflicting function)
  566.      */
  567.     function getFuncConflicts($name)
  568.     {
  569.         if (!isset($this->functionconflicts[$name])) return false;
  570.         $a array();
  571.         foreach($this->functionconflicts[$nameas $conflict)
  572.         {
  573.             foreach($this->functionsbyfile[$conflictas $i => $func)
  574.             {
  575.                 if ($func->getName(== $name)
  576.                 $a[$this->functionsbyfile[$conflict][$i]->docblock->package$this->functionsbyfile[$conflict][$i];
  577.             }
  578.         }
  579.         return $a;
  580.     }
  581.     
  582.     /**
  583.      * called by {@link parserGlobal::getConflicts()} to get inter-package conflicts, should not be called directly
  584.      * @access private
  585.      * @return array Format: (package => {@link parserGlobal} of conflicting global variable)
  586.      */
  587.     function getGlobalConflicts($name)
  588.     {
  589.         if (!isset($this->globalconflicts[$name])) return false;
  590.         $a array();
  591.         foreach($this->globalconflicts[$nameas $conflict)
  592.         {
  593.             foreach($this->globalsbyfile[$conflictas $i => $func)
  594.             {
  595.                 if ($func->getName(== $name)
  596.                 $a[$this->globalsbyfile[$conflict][$i]->docblock->package$this->globalsbyfile[$conflict][$i];
  597.             }
  598.         }
  599.         return $a;
  600.     }
  601.     
  602.     /**
  603.      * called by {@link parserDefine::getConflicts()} to get inter-package conflicts, should not be called directly
  604.      * @access private
  605.      * @return array Format: (package => {@link parserDefine} of conflicting define)
  606.      */
  607.     function getDefineConflicts($name)
  608.     {
  609.         if (!isset($this->defineconflicts[$name])) return false;
  610.         $a array();
  611.         foreach($this->defineconflicts[$nameas $conflict)
  612.         {
  613.             foreach($this->definesbyfile[$conflictas $i => $func)
  614.             {
  615.                 if ($func->getName(== $name)
  616.                 $a[$this->definesbyfile[$conflict][$i]->docblock->package$this->definesbyfile[$conflict][$i];
  617.             }
  618.         }
  619.         return $a;
  620.     }
  621.     
  622.     /**
  623.      * Adjusts packages of all pages and removes name conflicts within a package
  624.      *
  625.      * Automatic linking requires that each linkable name have exactly one element associated with it.  In other words, there
  626.      * cannot be two functions named foo() in the same package.  This also adheres to php rules with one exception:
  627.      *
  628.      * <code>
  629.      * if ($test == 3)
  630.      * {
  631.      *    define('whatever','this thing');
  632.      * } else
  633.      * {
  634.      *    define('whatever','this other thing');
  635.      * }
  636.      * </code>
  637.      *
  638.      * phpDocumentor is not aware of conditional control structures because it would slow things down considerably.
  639.      * So, what phpDocumentor does is automatically ignore the second define and raise a warning.  The warning can
  640.      * be eliminated with an @ignore tag on the second element like so:
  641.      *
  642.      * <code>
  643.      * if ($test == 3)
  644.      * {
  645.      *    define('whatever','this thing');
  646.      * } else
  647.      * {
  648.      *    /** @ignore {@*} 
  649.      *    define('whatever','this other thing');
  650.      * }
  651.      * </code>
  652.      *
  653.      * if there are two files that contain the same procedural elements in the same package (for example,
  654.      * a common configuration file common.php), they will also be ignored as if they were in the same file.  The
  655.      * reasoning behind this is simple.  A package is an indivisible set of files and classes that a user will
  656.      * include in their code.  Name conflicts must be avoided to allow successful execution.
  657.      *
  658.      * This function also plays the all-important role of calling {@link phpDocumentor_IntermediateParser::addElementToPage()} in
  659.      * order to add processed elements to their pages for Conversion.
  660.      * @param phpDocumentor_IntermediateParser &$render 
  661.      */
  662.     function setupPages(&$render)
  663.     {
  664.         global $_phpDocumentor_setting;
  665.         phpDocumentor_out("\nProcessing Procedural Page Element Name Conflicts\n\n");
  666.         flush();
  667.         $this->setupPagePackages();
  668.         $this->setupConflicts($render);
  669. //        phpDocumentor_out("\nProcessing Procedural Pages\n\n");
  670.         foreach($this->pathpages as $path => $name)
  671.         {
  672. //            phpDocumentor_out("Processing $path\n");
  673.             $a $this->pagepackages[$path];
  674.             $b &$this->pages[$name][$path];
  675.             $render->addPage($b$path);
  676.             $render->addUses($b$path);
  677.             if (isset($this->includesbyfile[$path]))
  678.             foreach($this->includesbyfile[$pathas $include)
  679.             {
  680.                 $include->docblock->package $a[0];
  681.                 $include->docblock->subpackage $a[1];
  682.                 $render->addElementToPage($include,$path);
  683.             }
  684.     
  685.             if (isset($this->functionsbyfile[$path]))
  686.             foreach($this->functionsbyfile[$pathas $function)
  687.             {
  688.                 $function->docblock->package $a[0];
  689.                 $function->docblock->subpackage $a[1];
  690.                 $render->addElementToPage($function,$path);
  691.                 $render->addUses($function,$path);
  692.             }
  693.     
  694.             if (isset($this->definesbyfile[$path]))
  695.             foreach($this->definesbyfile[$pathas $define)
  696.             {
  697.                 $define->docblock->package $a[0];
  698.                 $define->docblock->subpackage $a[1];
  699.                 $render->addElementToPage($define,$path);
  700.                 $render->addUses($define,$path);
  701.             }
  702.     
  703.             if (isset($this->globalsbyfile[$path]))
  704.             foreach($this->globalsbyfile[$pathas $global)
  705.             {
  706.                 $global->docblock->package $a[0];
  707.                 $global->docblock->subpackage $a[1];
  708.                 $render->addElementToPage($global,$path);
  709.                 $render->addUses($global,$path);
  710.             }
  711.         }
  712.     }
  713.     
  714.     function setParseBase($pbase)
  715.     {
  716.         $this->_parsedbase $pbase;
  717.     }
  718.     
  719.     /**
  720.      * @return false|parserPagereturns matched parserPage if found
  721.      */
  722.     function pathMatchesParsedFile($path$infile)
  723.     {
  724.         $test $this->getRealPath($path$infile);
  725.         if (is_string($test))
  726.         {
  727.             if (isset($this->pathpages[$test]))
  728.                 return $this->pages[$this->pathpages[$test]][$test];
  729.             if (PHPDOCUMENTOR_WINDOWS$test str_replace('/','\\',$test);
  730.             if (isset($this->pathpages[$test]))
  731.             {
  732.                 $a $this->pages[$this->pathpages[$test]][$test];
  733.                 if (is_array($a->packageOutput&& !in_array($a->package$a->packageOutput))
  734.                     return false;
  735.                 return $this->pages[$this->pathpages[$test]][$test];
  736.             }
  737.         else
  738.         {
  739.             foreach($test as $file)
  740.             {
  741.                 if (isset($this->pathpages[$file]))
  742.                     return $this->pages[$this->pathpages[$file]][$file];
  743.                 if (PHPDOCUMENTOR_WINDOWS$file str_replace('/','\\',$file);
  744.                 if (isset($this->pathpages[$file]))
  745.                 {
  746.                     $a $this->pages[$this->pathpages[$file]][$file];
  747.                     if (is_array($a->packageOutput&& !in_array($a->package$a->packageOutput))
  748.                         return false;
  749.                     return $this->pages[$this->pathpages[$file]][$file];
  750.                 }
  751.             }
  752.         }
  753.         return false;
  754.     }
  755.     
  756.     /**
  757.      * @param string include() statement path to check
  758.      * @param string full path of file the statement is in
  759.      * @param string full path to base directory of parsing, used for .
  760.      * @return array|stringreturns an array of possible file locations or
  761.      *                       a string if there is an exact match
  762.      */
  763.     function getRealPath($path$file)
  764.     {
  765.         $curdir str_replace('\\','/',dirname($file));
  766.         $path str_replace('\\','/',$path);
  767.         if (strpos($path,':'!== false)
  768.         // windows, and we have a drive letter
  769.             return $path;
  770.         elseif(strpos($path,'/'=== 0)
  771.         {
  772.             return $path;
  773.         }
  774.         // not an absolute path
  775.         $path explode('/',$path);
  776.         if ($path[0== '.')
  777.         {
  778.             $path[0dirname($file);
  779.             return join($path,'/');
  780.         elseif ($path[0== '..')
  781.         {
  782.             $dirfile explode('/',dirname(str_replace('\\','/',$file)));
  783.             array_pop($dirfile)// remove the current directory
  784.             if (!count($dirfile)) return false// we were at a top-level dir!
  785.             $path[0join($dirfile,'/')// replace .. with parent dirname
  786.             return join($path,'/');
  787.         else
  788.         {
  789.             $path join($path,'/');
  790.             return array($curdir PATH_DELIMITER $path,
  791.                          str_replace('\\','/',PHPDOCUMENTOR_BASEPATH_DELIMITER $path);
  792.         }
  793.     }
  794. }
  795. ?>

Documentation generated on Tue, 24 Oct 2006 09:25:59 -0500 by phpDocumentor 1.3.1