home *** CD-ROM | disk | FTP | other *** search
/ Cricao de Sites - 650 Layouts Prontos / WebMasters.iso / Servidores / xampp-win32-1.6.7-installer.exe / php / PEAR / phing / tasks / ext / phpdoc / PHPDocumentorTask.php < prev   
Encoding:
PHP Script  |  2007-10-17  |  10.0 KB  |  413 lines
  1. <?php
  2.  
  3. /**
  4.  * $Id: PHPDocumentorTask.php 144 2007-02-05 15:19:00Z hans $
  5.  *
  6.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  7.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  8.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  9.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  10.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  11.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  12.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  13.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  14.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  15.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  16.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  17.  *
  18.  * This software consists of voluntary contributions made by many individuals
  19.  * and is licensed under the LGPL. For more information please see
  20.  * <http://phing.info>.
  21.  */
  22.  
  23. require_once 'phing/Task.php';
  24.  
  25. /**
  26.  * Task to run PhpDocumentor.
  27.  *
  28.  * @author Hans Lellelid <hans@xmpl.org>
  29.  * @author Michiel Rook <michiel.rook@gmail.com>
  30.  * @version $Id$
  31.  * @package phing.tasks.ext.phpdoc
  32.  */    
  33. class PhpDocumentorTask extends Task
  34. {
  35.     
  36.     /**
  37.      * @var string Title for browser window / package index.
  38.      */
  39.     private $title;
  40.     
  41.     /**
  42.      * @var PhingFile The target directory for output files.
  43.      */
  44.     private $destdir;
  45.  
  46.     /**
  47.      * @var array FileSet[] Filesets for files to parse.
  48.      */
  49.     private $filesets = array();
  50.     
  51.     /**
  52.      * @var array FileSet[] Project documentation (README/INSTALL/CHANGELOG) files.
  53.      */
  54.     private $projDocFilesets = array();
  55.     
  56.     /**
  57.      * @var string Package output format. 
  58.      */
  59.     private $output;
  60.  
  61.     /**
  62.      * @var boolean Whether to generate sourcecode for each file parsed.
  63.      */
  64.     private $linksource = false;
  65.     
  66.     /**
  67.      * @var boolean Whether to parse private members.
  68.      */
  69.     private $parsePrivate = false;
  70.     
  71.     /**
  72.      * @var boolean Whether to use javadoc descriptions (more primitive).
  73.      */
  74.     private $javadocDesc = false;
  75.     
  76.     /**
  77.      * @var PhingFile Base directory for locating template files.
  78.      */
  79.     private $templateBase;
  80.     
  81.     /**
  82.      * @var boolean Wheter to suppress output.
  83.      */
  84.     private $quiet = false;
  85.     
  86.     /**
  87.      * @var string Comma-separated list of packages to output.
  88.      */
  89.     private $packages;
  90.     
  91.     /** 
  92.      * @var string Comma-separated list of tags to ignore.
  93.      */
  94.     private $ignoreTags;
  95.     
  96.     /** 
  97.      * @var string Default package name.
  98.      */
  99.     private $defaultPackageName;
  100.     
  101.     /**
  102.      * @var string Default category name.
  103.      */
  104.     private $defaultCategoryName;
  105.     
  106.     /**
  107.      * @var PhingFile Directory in which to look for examples.
  108.      */
  109.     private $examplesDir;
  110.     
  111.     /**
  112.      * @var PhingFile Directory in which to look for configuration files.
  113.      */
  114.     private $configDir;
  115.     
  116.     /**
  117.      * @var boolean Whether to parse as a PEAR repository.
  118.      */
  119.     private $pear = false;
  120.     
  121.     /**
  122.      * Set the title for the generated documentation
  123.      */
  124.     public function setTitle($title) {
  125.         $this->title = $title;
  126.     }
  127.  
  128.     /**
  129.      * Set the destination directory for the generated documentation
  130.      */
  131.     public function setDestdir(PhingFile $destdir) {
  132.         $this->destdir = $destdir;
  133.     }
  134.     
  135.     /**
  136.      * Alias for {@link setDestdir()).
  137.      * @see setDestdir()
  138.      */
  139.     public function setTarget(PhingFile $destdir) {
  140.         $this->setDestdir($destdir);
  141.     }
  142.  
  143.     /**
  144.      * Set the output format (e.g. HTML:Smarty:PHP).
  145.      * @param string $output
  146.      */        
  147.     public function setOutput($output) {
  148.         $this->output = $output;
  149.     }
  150.  
  151.     /**
  152.      * Set whether to generate sourcecode for each file parsed
  153.      * @param boolean
  154.      */
  155.     public function setSourcecode($b) {
  156.         $this->linksource = $b;
  157.     }
  158.     
  159.     /**
  160.      * Set whether to suppress output.
  161.      * @param boolean $b
  162.      */
  163.     public function setQuiet($b) {
  164.         $this->quiet = $b;
  165.     }
  166.     
  167.     /**
  168.      * Should private members/classes be documented
  169.      * @param boolean
  170.      */
  171.     public function setParseprivate($parseprivate) {
  172.         $this->parsePrivate = $parseprivate;
  173.     }
  174.     
  175.     /**
  176.      * Whether to use javadoc descriptions (more primitive).
  177.      * @param boolean
  178.      */
  179.     public function setJavadocdesc($javadoc) {
  180.         $this->javadocDesc = $javadoc;
  181.     }
  182.     
  183.     /**
  184.      * Set (comma-separated) list of packages to output.
  185.      *
  186.      * @param string $packages
  187.      */
  188.     public function setPackageoutput($packages) {
  189.         $this->packages = $packages;
  190.     }
  191.     
  192.     /**
  193.      * Set (comma-separated) list of tags to ignore.
  194.      *
  195.      * @param string $tags
  196.      */
  197.     public function setIgnoretags($tags) {
  198.         $this->ignoreTags = $tags;
  199.     }
  200.     
  201.     /**
  202.      * Set a directory to search for examples in.
  203.      * @param PhingFile $d
  204.      */
  205.     public function setExamplesdir(PhingFile $d) {
  206.         $this->examplesDir = $d;
  207.     }
  208.     
  209.     /**
  210.      * Set a directory to search for configuration files in.
  211.      * @param PhingFile $d
  212.      */
  213.     public function setConfigdir(PhingFile $d) {
  214.         $this->configDir = $d;
  215.     }
  216.     
  217.     /**
  218.      * Sets the default package name.
  219.      * @param string $name
  220.      */
  221.     public function setDefaultpackagename($name) {
  222.         $this->defaultPackageName = $name;
  223.     }
  224.     
  225.     /**
  226.      * Sets the default category name.
  227.      * @param string $name
  228.      */
  229.     public function setDefaultcategoryname($name) {
  230.         $this->defaultCategoryName = $name;
  231.     }
  232.     
  233.     /**
  234.      * Set whether to parse as PEAR repository.
  235.      * @param boolean $b
  236.      */
  237.     public function setPear($b) {
  238.         $this->pear = $b;
  239.     }
  240.     
  241.     /**
  242.      * Creates a FileSet.
  243.      * @return FileSet
  244.      */
  245.     public function createFileset() {
  246.         $num = array_push($this->filesets, new FileSet());
  247.         return $this->filesets[$num-1];
  248.     }
  249.     
  250.     /**
  251.      * Creates a readme/install/changelog fileset.
  252.      * @return FileSet
  253.      */
  254.     public function createProjdocfileset() {
  255.         $num = array_push($this->projDocFilesets, new FileSet());
  256.         return $this->projDocFilesets[$num-1];
  257.     }
  258.      
  259.     /**
  260.      * Searches include_path for PhpDocumentor install and adjusts include_path appropriately.
  261.      * @throws BuildException - if unable to find PhpDocumentor on include_path
  262.      */
  263.     protected function findPhpDocumentorInstall()
  264.     {
  265.         $found = null;
  266.         foreach(explode(PATH_SEPARATOR, get_include_path()) as $path) {
  267.             $testpath = $path . DIRECTORY_SEPARATOR . 'PhpDocumentor';
  268.             if (file_exists($testpath)) {
  269.                 $found = $testpath;
  270.                 break;
  271.             }
  272.         }
  273.         if (!$found) {
  274.             throw new BuildException("PhpDocumentor task depends on PhpDocumentor being installed and on include_path.", $this->getLocation());
  275.         }
  276.         // otherwise, adjust the include_path to path to include the PhpDocumentor directory ... 
  277.         set_include_path(get_include_path() . PATH_SEPARATOR . $found);
  278.         include_once ("phpDocumentor/Setup.inc.php");
  279.         if (!class_exists('phpDocumentor_setup')) {
  280.             throw new BuildException("Error including PhpDocumentor setup class file.");
  281.         }
  282.     }
  283.     
  284.     /**
  285.      * Load the necessary environment for running PhpDoc.
  286.      *
  287.      * @throws BuildException - if the phpdoc classes can't be loaded.
  288.      */
  289.     public function init()
  290.     {
  291.         $this->findPhpDocumentorInstall();
  292.         include_once 'phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php';
  293.     }
  294.     
  295.     /**
  296.      * Main entrypoint of the task
  297.      */
  298.     function main()
  299.     {
  300.         $this->validate();
  301.         $configdir = $this->configDir ? $this->configDir->getAbsolutePath() : null;
  302.         $phpdoc = new PhingPhpDocumentorSetup($configdir);
  303.         $this->setPhpDocumentorOptions($phpdoc);
  304.         //$phpdoc->readCommandLineSettings();
  305.         $phpdoc->setupConverters($this->output);
  306.         $phpdoc->createDocs();        
  307.     }
  308.     
  309.     /**
  310.      * Validates that necessary minimum options have been set.
  311.      * @throws BuildException if validation doesn't pass
  312.      */
  313.     protected function validate()
  314.     {
  315.         if (!$this->destdir) {
  316.             throw new BuildException("You must specify a destdir for phpdoc.", $this->getLocation());
  317.         }
  318.         if (!$this->output) {
  319.             throw new BuildException("You must specify an output format for phpdoc (e.g. HTML:frames:default).", $this->getLocation());
  320.         }
  321.         if (empty($this->filesets)) {
  322.             throw new BuildException("You have not specified any files to include (<fileset>) for phpdoc.", $this->getLocation());
  323.         }
  324.     }
  325.     
  326.     /**
  327.      * Sets the options on the passed-in phpdoc setup object.
  328.      * @param PhingPhpDocumentorSetup $phpdoc
  329.      */
  330.     protected function setPhpDocumentorOptions(PhingPhpDocumentorSetup $phpdoc)
  331.     {
  332.         
  333.         // Title MUST be set first ... (because it re-initializes the internal state of the PhpDocu renderer)
  334.         if ($this->title) {
  335.             $phpdoc->setTitle($this->title);
  336.         }
  337.         
  338.         if ($this->parsePrivate) {
  339.             $phpdoc->setParsePrivate();
  340.         }
  341.         
  342.         if ($this->javadocDesc) {
  343.             $phpdoc->setJavadocDesc();
  344.         }
  345.         
  346.         if ($this->quiet) {
  347.             $phpdoc->setQuietMode();
  348.         }
  349.         
  350.         if ($this->destdir) {
  351.             $phpdoc->setTargetDir($this->destdir->getAbsolutePath());
  352.         }
  353.                 
  354.         if ($this->packages) {
  355.             $phpdoc->setPackageOutput($this->packages);
  356.         }
  357.         
  358.         if ($this->templateBase) {
  359.             $phpdoc->setTemplateBase($this->templateBase->getAbsolutePath());
  360.         }
  361.         
  362.         if ($this->linksource) {
  363.             $phpdoc->setGenerateSourcecode($this->linksource);
  364.         }
  365.         
  366.         if ($this->examplesDir) {
  367.             $phpdoc->setExamplesDir($this->examplesDir->getAbsolutePath());
  368.         }
  369.         
  370.         if ($this->ignoreTags) {
  371.             $phpdoc->setIgnoreTags($this->ignoreTags);
  372.         }
  373.         
  374.         if ($this->defaultPackageName) {
  375.             $phpdoc->setDefaultPackageName($this->defaultPackageName);
  376.         }
  377.         
  378.         if ($this->defaultCategoryName) {
  379.             $phpdoc->setDefaultCategoryName($this->defaultCategoryName);
  380.         }
  381.         
  382.         if ($this->pear) {
  383.             $phpdoc->setPear($this->pear);
  384.         }
  385.         
  386.         // append any files in filesets
  387.         $filesToParse = array();
  388.         foreach($this->filesets as $fs) {            
  389.             $files = $fs->getDirectoryScanner($this->project)->getIncludedFiles();
  390.             foreach($files as $filename) {
  391.                  $f = new PhingFile($fs->getDir($this->project), $filename);
  392.                  $filesToParse[] = $f->getAbsolutePath();
  393.             }
  394.         }
  395.         //print_r(implode(",", $filesToParse));
  396.         $phpdoc->setFilesToParse(implode(",", $filesToParse));
  397.         
  398.         
  399.         // append any files in filesets
  400.         $ricFiles = array();
  401.         foreach($this->projDocFilesets as $fs) {            
  402.             $files = $fs->getDirectoryScanner($this->project)->getIncludedFiles();
  403.             foreach($files as $filename) {
  404.                  $f = new PhingFile($fs->getDir($this->project), $filename);
  405.                  $ricFiles[] = $f->getAbsolutePath();
  406.             }
  407.         }
  408.         $phpdoc->setRicFiles($ricFiles);
  409.         
  410.     }
  411.     
  412. }
  413.