Changeset 352

Show
Ignore:
Timestamp:
02/06/08 15:26:43 (5 months ago)
Author:
mrook
Message:

#210 - Improve and un-deprecate PhpDocumentorExternalTask (patch by Markus Fischer)

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

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

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

    r325 r352  
    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'; 
    41  
    42         private $title = "Default Title"; 
    43  
    44         private $destdir = "."; 
    45  
    46         private $sourcepath = NULL; 
    47  
    48         private $output = ""; 
    49  
    50         private $linksource = false; 
    51  
    52         private $parseprivate = false; 
     42        protected $programPath = 'phpdoc'; 
     43 
     44        protected $sourcepath = NULL; 
     45 
     46    /** 
     47     * @var bool  ignore symlinks to other files or directories 
     48     */ 
     49    protected $ignoresymlinks = false; 
    5350 
    5451        /** 
    5552         * Sets the path to the phpDocumentor executable 
    5653         */ 
    57         function setProgramPath($programPath) 
     54        public function setProgramPath($programPath) 
    5855        { 
    5956                $this->programPath = $programPath; 
    …… 
    6360         * Returns the path to the phpDocumentor executable 
    6461         */ 
    65         function getProgramPath() 
     62        public function getProgramPath() 
    6663        { 
    6764                return $this->programPath; 
    …… 
    6966 
    7067        /** 
    71          * Set the title for the generated documentation 
    72          */ 
    73         function setTitle($title) 
    74         { 
    75                 $this->title = $title; 
    76         } 
    77  
    78         /** 
    79          * Set the destination directory for the generated documentation 
    80          */ 
    81         function setDestdir($destdir) 
    82         { 
    83                 $this->destdir = $destdir; 
    84         } 
    85  
    86         /** 
    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         } 
     68     * Set the source path. A directory or a comma separate list of directories. 
     69         */ 
     70        public function setSourcepath($sourcepath) 
     71        { 
     72        $this->sourcepath = $sourcepath; 
     73        } 
     74 
     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    } 
    12483 
    12584        /** 
    12685         * Main entrypoint of the task 
    12786         */ 
    128         function main() 
    129         { 
    130                 $arguments = $this->constructArguments(); 
     87        public function main() 
     88        { 
     89        $this->validate(); 
     90                $arguments = join(' ', $this->constructArguments()); 
    13191 
    13292                $this->log("Running phpDocumentor..."); 
    …… 
    153113        /** 
    154114         * Constructs an argument string for phpDocumentor 
    155          */ 
    156         private function constructArguments() 
    157         { 
    158                $arguments = "-q on "; 
    159  
     115     * @return  array 
     116        */ 
     117        protected function constructArguments() 
     118        { 
     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 . "\" "; 
    168                 } 
    169  
    170                 if ($this->sourcepath !== NULL) 
    171                 { 
    172                         $arguments.= "-d \"" . $this->sourcepath->__toString() . "\" "; 
     127                        $aArgs[] = '--target "' . $this->destdir->getAbsolutePath() . '"'; 
     128                } 
     129 
     130                if ($this->sourcepath) 
     131                { 
     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 "; 
    188                 } 
    189  
    190                 return $arguments; 
    191         } 
     147                        $aArgs[] = '--parseprivate on'; 
     148                } 
     149 
     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; 
     226        } 
     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 
     261 

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

    r250 r352  
    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        /** 
    …… 
    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 
     282    /** 
     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 
    259301    /** 
    260302     * Searches include_path for PhpDocumentor install and adjusts include_path appropriately. 
    …… 
    407449                } 
    408450                $phpdoc->setRicFiles($ricFiles); 
    409                  
    410         } 
    411          
     451 
     452        if ($this->undocumentedelements) { 
     453            $phpdoc->setUndocumentedelements($this->undocumentedelements); 
     454        } 
     455 
     456        if ($this->customtags) { 
     457            $phpdoc->setCustomtags($this->customtags); 
     458        } 
     459        } 
    412460} 

  • branches/2.3/docs/phing_guide/book/chapters/appendixes/AppendixC-OptionalTasks.html

    r342 r352  
    11361136    </tr> 
    11371137 
     1138        <tr> 
     1139      <td>templatebase</td> 
     1140      <td>String</td> 
     1141      <td>Set base dirctory of all templates for this parse.</td> 
     1142      <td>n/a</td> 
     1143      <td>No</td> 
     1144    </tr> 
     1145 
     1146        <tr> 
     1147      <td>undocumentedelements</td> 
     1148      <td>Boolean</td> 
     1149      <td>Control whether or not warnings will be shown for undocumented 
     1150          elements. Useful for identifying classes and methods that haven't yet 
     1151          been documented.</td> 
     1152      <td>false</td> 
     1153      <td>No</td> 
     1154    </tr> 
     1155 
     1156        <tr> 
     1157      <td>customtags</td> 
     1158      <td>Boolean</td> 
     1159      <td>Custom tags, will be recognized and put in tags[] instead of 
     1160          unknowntags[].</td> 
     1161      <td>false</td> 
     1162      <td>No</td> 
     1163    </tr> 
     1164 
    11381165  </tbody> 
    11391166</table> 
    …… 
    11611188&lt;/phpdoc&gt; 
    11621189</pre> 
     1190 
     1191<h2><a name="PhpDocumentorExternalTask"></a>PhpDocumentorExternalTask</h2> 
     1192<p>This is the same as the <a href="#PhpDocumentorTask">PhpDocumentorTask</a> 
     1193but uses the command line application. Use this as a fallback in case you're 
     1194running into troubles when using the phpDocumentor-library with the 
     1195PhpDocumentorTask directly, e.g. when you're using Smarty and have Smarty in 
     1196your library path too.</p> 
     1197<p>This task supports everything the PhpDocumentorTask supports, differences are 
     1198documented below.</p> 
     1199<h3>Additional attributes</h3> 
     1200<table> 
     1201  <thead> 
     1202    <tr> 
     1203      <th>Name</th> 
     1204      <th>Type</th> 
     1205      <th>Description</th> 
     1206      <th>Default</th> 
     1207      <th>Required</th> 
     1208    </tr> 
     1209  </thead> 
     1210  <tbody> 
     1211    <tr> 
     1212      <td>programpath</td> 
     1213      <td>String</td> 
     1214      <td>Path to the phpdoc executable (relative or absolute).</td> 
     1215      <td>n/a</td> 
     1216      <td>No</td> 
     1217    </tr> 
     1218 
     1219    <tr> 
     1220      <td>sourcepath</td> 
     1221      <td>String</td> 
     1222      <td>A directory to scan for parsable files. Supports multiple directories 
     1223          separated with a comma.</td> 
     1224      <td>n/a</td> 
     1225      <td>Yes, if no <tt>&lt;fileset&gt;</tt> is given</td> 
     1226    </tr> 
     1227 
     1228  </tbody> 
     1229</table> 
     1230 
     1231<h3>Unsupported attributes</h3> 
     1232<table> 
     1233  <thead> 
     1234    <tr> 
     1235      <th>Name</th> 
     1236      <th>Description</th> 
     1237    </tr> 
     1238  </thead> 
     1239  <tbody> 
     1240 
     1241    <tr> 
     1242      <td>configdir</td> 
     1243      <td>Currently not supported. The attribute will be ignored and a 
     1244          warning messag will be generated. The build continues (to ease when 
     1245          changing an existing phpdoc task) however this may have unexpected 
     1246          side effects.</td> 
     1247    </tr> 
     1248 
     1249  </tbody> 
     1250</table> 
    11631251 
    11641252<h2><a name="PhpLintTask"></a>PhpLintTask</h2> 

  • branches/2.3/docs/phing_guide/book/toc/FrameToC.html

    r336 r352  
    134134<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PhpCodeSnifferTask" target="Content">PhpCodeSnifferTask</a></li> 
    135135<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PhpDocumentorTask" target="Content">PhpDocumentorTask</a></li> 
     136<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PhpDocumentorExternalTask" target="Content">PhpDocumentorExternalTask</a></li> 
    136137<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PhpLintTask" target="Content">PhpLintTask</a></li> 
    137138<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PHPUnitTask" target="Content">PHPUnitTask</a></li> 

  • branches/2.3/docs/phing_guide/book/toc/ToC.html

    r336 r352  
    119119<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PhpCodeSnifferTask">PhpCodeSnifferTask</a></li> 
    120120<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PhpDocumentorTask">PhpDocumentorTask</a></li> 
     121<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PhpDocumentorExternalTask">PhpDocumentorExternalTask</a></li> 
    121122<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PhpLintTask">PhpLintTask</a></li> 
    122123<li><a href="../chapters/appendixes/AppendixC-OptionalTasks.html#PHPUnitTask">PHPUnitTask</a></li>