Ticket #210: phing-phpdocext-rework-php.diff

File phing-phpdocext-rework-php.diff, 13.5 KB (added by Markus Fischer <markus@…>, 4 years ago)

Reworked PhpDocumentorExternalTask

  • classes/phing/tasks/ext/phpdoc/PhpDocumentorTask.php

     
    3636        /** 
    3737         * @var string Title for browser window / package index. 
    3838         */ 
    39         private $title; 
     39        protected $title; 
    4040         
    4141        /** 
    4242         * @var PhingFile The target directory for output files. 
    4343         */ 
    44         private $destdir; 
     44        protected $destdir; 
    4545 
    4646        /** 
    4747         * @var array FileSet[] Filesets for files to parse. 
    4848         */ 
    49         private $filesets = array(); 
     49        protected $filesets = array(); 
    5050         
    5151        /** 
    5252         * @var array FileSet[] Project documentation (README/INSTALL/CHANGELOG) files. 
    5353         */ 
    54         private $projDocFilesets = array(); 
     54        protected $projDocFilesets = array(); 
    5555         
    5656        /** 
    5757         * @var string Package output format.  
    5858         */ 
    59         private $output; 
     59        protected $output; 
    6060 
    6161        /** 
    6262         * @var boolean Whether to generate sourcecode for each file parsed. 
    6363         */ 
    64         private $linksource = false; 
     64        protected $linksource = false; 
    6565         
    6666        /** 
    6767         * @var boolean Whether to parse private members. 
    6868         */ 
    69         private $parsePrivate = false; 
     69        protected $parsePrivate = false; 
    7070         
    7171        /** 
    7272         * @var boolean Whether to use javadoc descriptions (more primitive). 
    7373         */ 
    74         private $javadocDesc = false; 
     74        protected $javadocDesc = false; 
    7575         
    7676        /** 
    7777         * @var PhingFile Base directory for locating template files. 
    7878         */ 
    79         private $templateBase; 
     79        protected $templateBase; 
    8080         
    8181        /** 
    8282         * @var boolean Wheter to suppress output. 
    8383         */ 
    84         private $quiet = false; 
     84        protected $quiet = false; 
    8585         
    8686        /** 
    8787         * @var string Comma-separated list of packages to output. 
    8888         */ 
    89         private $packages; 
     89        protected $packages; 
    9090         
    9191        /**  
    9292         * @var string Comma-separated list of tags to ignore. 
    9393         */ 
    94         private $ignoreTags; 
     94        protected $ignoreTags; 
    9595         
    9696        /**  
    9797         * @var string Default package name. 
    9898         */ 
    99         private $defaultPackageName; 
     99        protected $defaultPackageName; 
    100100         
    101101        /** 
    102102         * @var string Default category name. 
    103103         */ 
    104         private $defaultCategoryName; 
     104        protected $defaultCategoryName; 
    105105         
    106106        /** 
    107107         * @var PhingFile Directory in which to look for examples. 
    108108         */ 
    109         private $examplesDir; 
     109        protected $examplesDir; 
    110110         
    111111        /** 
    112112         * @var PhingFile Directory in which to look for configuration files. 
    113113         */ 
    114         private $configDir; 
     114        protected $configDir; 
    115115         
    116116        /** 
    117117         * @var boolean Whether to parse as a PEAR repository. 
    118118         */ 
    119         private $pear = false; 
     119        protected $pear = false; 
     120 
     121    /** 
     122     * @var boolean Control whether or not warnings will be shown for 
     123     *              undocumented elements. Useful for identifying classes and 
     124     *              methods that haven't yet been documented. 
     125     */ 
     126    protected $undocumentedelements = false; 
     127 
     128    /** 
     129     * @var string  custom tags, will be recognized and put in tags[] instead of 
     130     *              unknowntags[]. 
     131     */ 
     132    protected $customtags = ''; 
    120133         
    121134        /** 
    122135         * Set the title for the generated documentation 
    … …  
    256269        return $this->projDocFilesets[$num-1]; 
    257270    } 
    258271         
     272        /** 
     273     * Control whether or not warnings will be shown for undocumented elements. 
     274     * Useful for identifying classes and methods that haven't yet been 
     275     * documented. 
     276         * @param boolean $b 
     277         */ 
     278        public function setUndocumentedelements($b) { 
     279                $this->undocumentedelements = $b; 
     280        } 
     281 
    259282    /** 
     283     * custom tags, will be recognized and put in tags[] instead of 
     284     * unknowntags[]. 
     285     *  
     286     * @param  string  $sCustomtags  
     287     */ 
     288    public function setCustomtags($sCustomtags) { 
     289        $this->customtags = $sCustomtags; 
     290    } 
     291 
     292        /** 
     293         * Set base location of all templates for this parse. 
     294         *  
     295         * @param  PhingFile  $destdir  
     296         */ 
     297        public function setTemplateBase(PhingFile $oTemplateBase) { 
     298                $this->templateBase = $oTemplateBase; 
     299        } 
     300 
     301    /** 
    260302     * Searches include_path for PhpDocumentor install and adjusts include_path appropriately. 
    261303     * @throws BuildException - if unable to find PhpDocumentor on include_path 
    262304     */ 
    … …  
    406448                } 
    407449                } 
    408450                $phpdoc->setRicFiles($ricFiles); 
    409                  
     451 
     452        if ($this->undocumentedelements) { 
     453            $phpdoc->setUndocumentedelements($this->undocumentedelements); 
     454        } 
     455 
     456        if ($this->customtags) { 
     457            $phpdoc->setCustomtags($this->customtags); 
     458        } 
    410459        } 
    411          
    412460} 

  • classes/phing/tasks/ext/phpdoc/PhpDocumentorExternalTask.php

     
    2020 * <http://phing.info>. 
    2121 */ 
    2222 
    23 require_once 'phing/Task.php'; 
     23require_once 'phing/tasks/ext/phpdoc/PhpDocumentorTask.php'; 
    2424 
    2525/** 
    26  * Task to run phpDocumentor. 
     26 * Task to run phpDocumentor with an external process 
    2727 *  
    2828 * This classes uses the commandline phpdoc script to build documentation. 
     29 * Use this task instead of the PhpDocumentorTask when you've a clash with the 
     30 * Smarty libraries. 
    2931 * 
    3032 * @author Michiel Rook <michiel.rook@gmail.com> 
     33 * @author Markus Fischer <markus@fischer.name> 
    3134 * @version $Id$ 
    3235 * @package phing.tasks.ext.phpdoc 
    33  * @deprecated This task is being replaced by the new PhpDocumentorTask 
    3436 */      
    35 class PhpDocumentorExternalTask extends Task 
     37class PhpDocumentorExternalTask extends PhpDocumentorTask 
    3638{ 
    3739        /** 
    3840         * The path to the executable for phpDocumentor 
    3941         */ 
    40         private $programPath = 'phpdoc'; 
     42        protected $programPath = 'phpdoc'; 
    4143 
    42         private $title = "Default Title"; 
     44        protected $sourcepath = NULL; 
    4345 
    44         private $destdir = "."; 
     46    /** 
     47     * @var bool  ignore symlinks to other files or directories 
     48     */ 
     49    protected $ignoresymlinks = false; 
    4550 
    46         private $sourcepath = NULL; 
    47  
    48         private $output = ""; 
    49  
    50         private $linksource = false; 
    51  
    52         private $parseprivate = false; 
    53  
    5451        /** 
    5552         * Sets the path to the phpDocumentor executable 
    5653         */ 
    57         function setProgramPath($programPath) 
     54        public function setProgramPath($programPath) 
    5855        { 
    5956                $this->programPath = $programPath; 
    6057        } 
    … …  
    6259        /** 
    6360         * Returns the path to the phpDocumentor executable 
    6461         */ 
    65         function getProgramPath() 
     62        public function getProgramPath() 
    6663        { 
    6764                return $this->programPath; 
    6865        } 
    6966 
    7067        /** 
    71          * Set the title for the generated documentation 
     68     * Set the source path. A directory or a comma separate list of directories. 
    7269         */ 
    73         function setTitle($title) 
     70        public function setSourcepath($sourcepath) 
    7471        { 
    75                 $this->title = $title; 
     72        $this->sourcepath = $sourcepath; 
    7673        } 
    7774 
    78         /** 
    79          * Set the destination directory for the generated documentation 
    80          */ 
    81         function setDestdir($destdir) 
    82         { 
    83                 $this->destdir = $destdir; 
    84         } 
     75    /** 
     76     * Ignore symlinks to other files or directories. 
     77     *  
     78     * @param  bool  $bSet  
     79     */ 
     80    public function setIgnoresymlinks($bSet) { 
     81        $this->ignoresymlinks = $bSet; 
     82    } 
    8583 
    8684        /** 
    87          * Set the source path 
    88          */ 
    89         function setSourcepath(Path $sourcepath) 
    90         { 
    91                 if ($this->sourcepath === NULL) 
    92                 { 
    93                         $this->sourcepath = $sourcepath; 
    94                 } 
    95                 else 
    96                 { 
    97                         $this->sourcepath->append($sourcepath); 
    98                 } 
    99         } 
    100  
    101         /** 
    102          * Set the output type 
    103          */              
    104         function setOutput($output) 
    105         { 
    106                 $this->output = $output; 
    107         } 
    108  
    109         /** 
    110          * Should sources be linked in the generated documentation 
    111          */ 
    112         function setLinksource($linksource) 
    113         { 
    114                 $this->linksource = $linksource; 
    115         } 
    116  
    117         /** 
    118          * Should private members/classes be documented 
    119          */ 
    120         function setParseprivate($parseprivate) 
    121         { 
    122                 $this->parseprivate = $parseprivate; 
    123         } 
    124  
    125         /** 
    12685         * Main entrypoint of the task 
    12786         */ 
    128         function main() 
     87        public function main() 
    12988        { 
    130                 $arguments = $this->constructArguments(); 
     89        $this->validate(); 
     90                $arguments = join(' ', $this->constructArguments()); 
    13191 
    13292                $this->log("Running phpDocumentor..."); 
    13393 
    … …  
    152112 
    153113        /** 
    154114         * Constructs an argument string for phpDocumentor 
     115     * @return  array 
    155116         */ 
    156         private function constructArguments() 
     117        protected function constructArguments() 
    157118        { 
    158                 $arguments = "-q on "; 
    159  
     119        $aArgs = array(); 
    160120                if ($this->title) 
    161121                { 
    162                         $arguments.= "-ti \"" . $this->title . "\" "; 
     122                        $aArgs[] = '--title "' . $this->title . '"'; 
    163123                } 
    164124 
    165125                if ($this->destdir) 
    166126                { 
    167                         $arguments.= "-t \"" . $this->destdir . "\" "; 
     127                        $aArgs[] = '--target "' . $this->destdir->getAbsolutePath() . '"'; 
    168128                } 
    169129 
    170                 if ($this->sourcepath !== NULL) 
     130                if ($this->sourcepath) 
    171131                { 
    172                         $arguments.= "-d \"" . $this->sourcepath->__toString() . "\" "; 
     132                        $aArgs[] = '--directory "' . $this->sourcepath . '"'; 
    173133                } 
    174134 
    175135                if ($this->output) 
    176136                { 
    177                         $arguments.= "-o " . $this->output . " "; 
     137                        $aArgs[] = '--output ' . $this->output; 
    178138                } 
    179139 
    180140                if ($this->linksource) 
    181141                { 
    182                         $arguments.= "-s on "; 
     142                        $aArgs[] = '--sourcecode on'; 
    183143                } 
    184144 
    185145                if ($this->parseprivate) 
    186146                { 
    187                         $arguments.= "-pp on "; 
     147                        $aArgs[] = '--parseprivate on'; 
    188148                } 
    189149 
    190                 return $arguments; 
     150                // append any files in filesets 
     151                $filesToParse = array(); 
     152                foreach($this->filesets as $fs) {                    
     153                $files = $fs->getDirectoryScanner($this->project)->getIncludedFiles(); 
     154                foreach($files as $filename) { 
     155                         $f = new PhingFile($fs->getDir($this->project), $filename); 
     156                         $filesToParse[] = $f->getAbsolutePath(); 
     157                } 
     158                } 
     159        if (count($filesToParse) > 0) { 
     160            $aArgs[] = '--filename "' . join(',', $filesToParse) . '"'; 
     161        } 
     162 
     163                // append any files in filesets 
     164                $ricFiles = array(); 
     165                foreach($this->projDocFilesets as $fs) {                     
     166                $files = $fs->getDirectoryScanner($this->project)->getIncludedFiles(); 
     167                foreach($files as $filename) { 
     168                         $f = new PhingFile($fs->getDir($this->project), $filename); 
     169                         $ricFiles[] = $f->getAbsolutePath(); 
     170                } 
     171                } 
     172        if (count($ricFiles) > 0) { 
     173            $aArgs[] = '--readmeinstallchangelog "' . 
     174                join(',', $ricFiles) . '"'; 
     175        } 
     176 
     177        if ($this->javadocDesc) { 
     178            $aArgs[] = '--javadocdesc on'; 
     179        } 
     180 
     181        if ($this->quiet) { 
     182            $aArgs[] = '--quiet on'; 
     183        } 
     184 
     185        if ($this->packages) { 
     186            $aArgs[] = '--packageoutput "' . $this->packages . '"'; 
     187        } 
     188 
     189        if ($this->ignoreTags) { 
     190            $aArgs[] = '--ignore-tags "' . $this->ignoreTags . '"'; 
     191        } 
     192 
     193        if ($this->defaultCategoryName) { 
     194            $aArgs[] = '--defaultcategoryname "' . $this->defaultCategoryName . 
     195                '"'; 
     196        } 
     197 
     198                if ($this->examplesDir) { 
     199            $aArgs[] = '--examplesdir "' . $this->examplesDir->getAbsolutePath() 
     200                . '"'; 
     201                } 
     202 
     203                if ($this->templateBase) { 
     204            $aArgs[] = '--templatebase "' . $this->templateBase->getAbsolutePath() 
     205                . '"'; 
     206                } 
     207 
     208        if ($this->pear) { 
     209            $aArgs[] = '--pear on'; 
     210        } 
     211 
     212        if ($this->undocumentedelements) { 
     213            $aArgs[] = '--undocumentedelements on'; 
     214        } 
     215 
     216        if ($this->customtags) { 
     217            $aArgs[] = '--customtags "' . $this->customtags . '"'; 
     218        } 
     219 
     220        if ($this->ignoresymlinks) { 
     221            $aArgs[] = '--ignoresymlinks on'; 
     222        } 
     223 
     224        var_dump($aArgs);exit; 
     225        return $aArgs; 
    191226        } 
     227 
     228    /** 
     229     * Override PhpDocumentorTask::init() because they're specific to the phpdoc 
     230     * API which we don't use. 
     231     */ 
     232    public function init() { 
     233    } 
     234 
     235    /** 
     236     * Validates that necessary minimum options have been set. Based on 
     237     * PhpDocumentorTask::validate(). 
     238     */ 
     239    protected function validate() { 
     240                if (!$this->destdir) { 
     241            throw new BuildException("You must specify a destdir for phpdoc.", 
     242                $this->getLocation()); 
     243                } 
     244                if (!$this->output) { 
     245            throw new BuildException("You must specify an output format for " . 
     246                "phpdoc (e.g. HTML:frames:default).", $this->getLocation()); 
     247                } 
     248                if (empty($this->filesets) && !$this->sourcepath) { 
     249            throw new BuildException("You have not specified any files to " . 
     250                "include (<fileset> or sourcepath attribute) for phpdoc.", 
     251                    $this->getLocation()); 
     252                } 
     253        if ($this->configdir) { 
     254            $this->log('Ignoring unsupported configdir-Attribute', 
     255                Project::MSG_VERBOSE); 
     256        } 
     257    } 
    192258}; 
    193259 
    194260 

  • classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php

     
    172172                $_phpDocumentor_setting['quiet'] = true; 
    173173                parent::setQuietMode(); 
    174174        } 
    175          
    176 } 
    177  No newline at end of file 
     175 
     176    /** 
     177     * Control whether or not warnings will be shown for undocumented elements. 
     178     * Useful for identifying classes and methods that haven't yet been 
     179     * documented. 
     180     *  
     181     * @param  bool  $bEnable  
     182     */ 
     183    public function setUndocumentedelements($bEnable) { 
     184        $this->render->setUndocumentedElementWarningsMode($bEnable); 
     185    } 
     186 
     187    /** 
     188     * custom tags, will be recognized and put in tags[] instead of 
     189     * unknowntags[] 
     190     * 
     191     * This method exists as a hack because the API exposed for this method in 
     192     * PhpDocumentor doesn't work correctly. 
     193         *  
     194     * Note that because we are setting a "private" GLOBAL(!!) config var with 
     195     * this value, this is subject to break if PhpDocumentor internals changes. 
     196     *  
     197     * @param  string  $sCustomtags  
     198     */ 
     199    public function setCustomtags($sCustomtags) { 
     200        global $_phpDocumentor_setting; 
     201        $_phpDocumentor_setting['customtags'] = $sCustomtags; 
     202    } 
     203}