Changeset 158

Show
Ignore:
Timestamp:
02/15/07 15:41:22 (2 years ago)
Author:
hans
Message:

References #76 - Update documentation for phpdoc task, add missing config options, and update coding style

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r156 r158  
    3838         * 
    3939         */ 
    40         public function __construct() 
    41         { 
     40        public function __construct() { 
    4241                global $_phpDocumentor_cvsphpfile_exts, $_phpDocumentor_setting; 
    4342                 
    …… 
    4746        $this->parseIni(); 
    4847                 
    49                 if (tokenizer_ext) 
    50         { 
    51             phpDocumentor_out("using tokenizer Parser\n"); 
     48                if (tokenizer_ext) { 
    5249            $this->parse = new phpDocumentorTParser(); 
    53         } else 
    54         { 
    55             phpDocumentor_out("using default (slower) Parser - get PHP 4.3.0+ 
    56 and load the tokenizer extension for faster parsing (your version is ".phpversion()."\n"); 
     50        } else { 
    5751            $this->parse = new Parser(); 
    5852        } 
    …… 
    6862         * @param bool $b 
    6963         */ 
    70         public function setGenerateSourcecode($b) 
    71         { 
     64        public function setGenerateSourcecode($b) { 
    7265                global $_phpDocumentor_setting; 
    7366                $_phpDocumentor_setting['sourcecode'] = (boolean) $b; 
    7467        } 
    7568         
     69        /** 
     70         * Set an array of README/INSTALL/CHANGELOG file paths.  
     71         * 
     72         * This method exists as a hack because there is no API exposed for this in PhpDocumentor. 
     73         * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this 
     74         * is subject to break if PhpDocumentor internals changes.   
     75         *  
     76         * @param array $files Absolute paths to files. 
     77         */ 
     78        public function setRicFiles($files) { 
     79                global $_phpDocumentor_RIC_files; 
     80                $_phpDocumentor_RIC_files = $files; 
     81        } 
     82         
     83        /** 
     84         * Set comma-separated list of tags to ignore. 
     85         * 
     86         * This method exists as a hack because there is no API exposed for this in PhpDocumentor. 
     87         * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this 
     88         * is subject to break if PhpDocumentor internals changes.   
     89         *  
     90         * @param string $tags 
     91         */ 
     92        public function setIgnoreTags($tags) { 
     93                global $_phpDocumentor_setting;  
     94                $ignoretags = explode(',', $tags); 
     95                $ignoretags = array_map('trim', $ignoretags); 
     96                $tags = array(); 
     97                foreach($ignoretags as $tag) { 
     98                    if (!in_array($tag,array('@global', '@access', '@package', '@ignore', '@name', '@param', '@return', '@staticvar', '@var'))) 
     99                        $tags[] = $tag; 
     100                } 
     101                $_phpDocumentor_setting['ignoretags'] = $tags; 
     102        } 
     103         
     104        /** 
     105         * Set whether to parse dirs as PEAR repos.  
     106         * 
     107         * This method exists as a hack because there is no API exposed for this in PhpDocumentor. 
     108         * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this 
     109         * is subject to break if PhpDocumentor internals changes.   
     110         *  
     111         * @param bool $b 
     112         */ 
     113        public function setPear($b) { 
     114                global $_phpDocumentor_setting; 
     115                $_phpDocumentor_setting['pear'] = (boolean) $b; 
     116        } 
     117         
     118        /** 
     119         * Set fullpath to directory to look in for examples.  
     120         * 
     121         * This method exists as a hack because there is no API exposed for this in PhpDocumentor. 
     122         * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this 
     123         * is subject to break if PhpDocumentor internals changes.   
     124         *  
     125         * @param string $dir 
     126         */ 
     127        public function setExamplesDir($dir) { 
     128                global $_phpDocumentor_setting; 
     129                $_phpDocumentor_setting['examplesdir'] = $dir; 
     130        } 
     131         
     132        /** 
     133         * Sets the default package name. 
     134         * 
     135         * This method exists as a hack because there is no API exposed for this in PhpDocumentor. 
     136         * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this 
     137         * is subject to break if PhpDocumentor internals changes.   
     138         *  
     139         * @param string $name 
     140         */ 
     141        public function setDefaultPackageName($name) { 
     142                $GLOBALS['phpDocumentor_DefaultPackageName'] = trim($name); 
     143        } 
     144         
     145        /** 
     146         * Sets the default category name. 
     147         * 
     148         * This method exists as a hack because there is no API exposed for this in PhpDocumentor. 
     149         * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this 
     150         * is subject to break if PhpDocumentor internals changes.   
     151         *  
     152         * @param string $name 
     153         */ 
     154        public function setDefaultCategoryName($name) { 
     155                $GLOBALS['phpDocumentor_DefaultCategoryName'] = trim($name); 
     156        } 
     157         
     158        /** 
     159         * Enables quiet mode. 
     160         * 
     161         * This method exists as a hack because the API exposed for this method in PhpDocumentor 
     162         * doesn't work correctly. 
     163         *  
     164         * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this 
     165         * is subject to break if PhpDocumentor internals changes.   
     166         *  
     167         */ 
     168        public function setQuietMode() { 
     169                global $_phpDocumentor_setting; 
     170                $_phpDocumentor_setting['quiet'] = true; 
     171                parent::setQuietMode(); 
     172        } 
     173         
    76174} 

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

    r157 r158  
    3535         
    3636        /** 
    37          * Title for browser window / package index. 
    38          * 
    39          * @var string 
     37         * @var string Title for browser window / package index. 
    4038         */ 
    4139        private $title; 
    4240         
    4341        /** 
    44          * The target directory for output files. 
    45          * 
    46          * @var PhingFile 
     42         * @var PhingFile The target directory for output files. 
    4743         */ 
    4844        private $destdir; 
    4945 
    5046        /** 
    51          * Filesets for files to parse. 
    52          * 
    53          * @var array FileSet[] 
     47         * @var array FileSet[] Filesets for files to parse. 
    5448         */ 
    5549        private $filesets = array(); 
    56                  
    57         /** 
    58          * Package output format. 
    59          * 
    60          * @var string  
     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.  
    6158         */ 
    6259        private $output; 
    6360 
    6461        /** 
    65          * Whether to generate sourcecode for each file parsed. 
    66          * 
    67          * @var boolean 
     62         * @var boolean Whether to generate sourcecode for each file parsed. 
    6863         */ 
    6964        private $linksource = false; 
    7065         
    7166        /** 
    72          * Whether to parse private members. 
    73          * 
    74          * @var boolean 
     67         * @var boolean Whether to parse private members. 
    7568         */ 
    7669        private $parsePrivate = false; 
    77  
    78         /** 
    79          * Whether to parse hidden files. 
    80          * 
    81          * @var boolean 
    82          */ 
    83         private $parseHiddenFiles = false; 
    84          
    85         /** 
    86          * Whether to use javadoc descriptions (more primitive). 
    87          * 
    88          * @var boolean 
     70         
     71        /** 
     72         * @var boolean Whether to use javadoc descriptions (more primitive). 
    8973         */ 
    9074        private $javadocDesc = false; 
    9175         
    9276        /** 
    93          * Base directory for locating template files. 
    94          * 
    95          * @var PhingFile 
     77         * @var PhingFile Base directory for locating template files. 
    9678         */ 
    9779        private $templateBase; 
    9880         
    9981        /** 
    100          * Wheter to suppress output. 
    101          *  
    102          * @var boolean 
     82         * @var boolean Wheter to suppress output. 
    10383         */ 
    10484        private $quiet = false; 
    10585         
    10686        /** 
    107          * Comma-separated list of packages to output. 
    108          * @var string 
     87         * @var string Comma-separated list of packages to output. 
    10988         */ 
    11089        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 boolean Whether to parse as a PEAR repository. 
     113         */ 
     114        private $pear = false; 
    111115         
    112116        /** 
    …… 
    122126        public function setDestdir(PhingFile $destdir) { 
    123127                $this->destdir = $destdir; 
     128        } 
     129         
     130        /** 
     131         * Alias for {@link setDestdir()). 
     132         * @see setDestdir() 
     133         */ 
     134        public function setTarget(PhingFile $destdir) { 
     135                $this->setDestdir($destdir); 
    124136        } 
    125137 
    …… 
    136148         * @param boolean 
    137149         */ 
    138         public function setLinksource($linksource) { 
    139                 $this->linksource = $linksource; 
    140         } 
    141  
     150        public function setSourcecode($b) { 
     151                $this->linksource = $b; 
     152        } 
     153         
     154        /** 
     155         * Set whether to suppress output. 
     156         * @param boolean $b 
     157         */ 
     158        public function setQuiet($b) { 
     159                $this->quiet = $b; 
     160        } 
     161         
    142162        /** 
    143163         * Should private members/classes be documented 
    …… 
    146166        public function setParseprivate($parseprivate) { 
    147167                $this->parseprivate = $parseprivate; 
    148         } 
    149          
    150         /** 
    151          * WHether to parse hidden files. 
    152          * 
    153          * @param boolean $parsehidden 
    154          */ 
    155         public function setParsehiddenfiles($parsehidden) { 
    156                 $this->parseHiddenFiles = $parsehidden; 
    157168        } 
    158169         
    …… 
    170181         * @param string $packages 
    171182         */ 
    172         public function setPackages($packages) 
    173         { 
     183        public function setPackageoutput($packages) { 
    174184                $this->packages = $packages; 
    175185        } 
    176              
     186         
     187        /** 
     188         * Set (comma-separated) list of tags to ignore. 
     189         * 
     190         * @param string $tags 
     191         */ 
     192        public function setIgnoretags($tags) { 
     193                $this->ignoreTags = $tags; 
     194        } 
     195         
     196        /** 
     197         * Set a directory to search for examples in. 
     198         * @param PhingFile $d 
     199         */ 
     200        public function setExamplesdir(PhingFile $d) { 
     201                $this->examplesDir = $d; 
     202        } 
     203         
     204        /** 
     205         * Sets the default package name. 
     206         * @param string $name 
     207         */ 
     208        public function setDefaultpackagename($name) { 
     209                $this->defaultPackageName = $name; 
     210        } 
     211         
     212        /** 
     213         * Sets the default category name. 
     214         * @param string $name 
     215         */ 
     216        public function setDefaultcategoryname($name) { 
     217                $this->defaultCategoryName = $name; 
     218        } 
     219         
     220        /** 
     221         * Set whether to parse as PEAR repository. 
     222         * @param boolean $b 
     223         */ 
     224        public function setPear($b) { 
     225                $this->pear = $b; 
     226        } 
     227         
    177228    /** 
    178229         * Creates a FileSet. 
    179230         * @return FileSet 
    180231         */ 
    181     public function createFileSet() { 
     232    public function createFileset() { 
    182233        $num = array_push($this->filesets, new FileSet()); 
    183234        return $this->filesets[$num-1]; 
    184     }          
     235    } 
     236     
     237    /** 
     238     * Creates a readme/install/changelog fileset. 
     239     * @return FileSet 
     240     */ 
     241    public function createProjdocfileset() { 
     242        $num = array_push($this->projDocFilesets, new FileSet()); 
     243        return $this->projDocFilesets[$num-1]; 
     244    } 
    185245         
    186246    /** 
    …… 
    266326                } 
    267327                 
    268                 if ($this->parseHiddenFiles) { 
    269                         $phpdoc->parseHiddenFiles(); 
    270                 } 
    271                  
    272328                if ($this->javadocDesc) { 
    273329                        $phpdoc->setJavadocDesc(); 
    …… 
    279335                 
    280336                if ($this->destdir) { 
    281                         $this->log("Setting target dir to: " . $this->destdir->getAbsolutePath()); 
    282337                        $phpdoc->setTargetDir($this->destdir->getAbsolutePath()); 
    283338                } 
    284                  
    285                  
    286                  
     339                                 
    287340                if ($this->packages) { 
    288341                        $phpdoc->setPackageOutput($this->packages); 
    …… 
    295348                if ($this->linksource) { 
    296349                        $phpdoc->setGenerateSourcecode($this->linksource); 
     350                } 
     351                 
     352                if ($this->examplesDir) { 
     353                        $phpdoc->setExamplesDir($this->examplesDir->getAbsolutePath()); 
     354                } 
     355                 
     356                if ($this->ignoreTags) { 
     357                        $phpdoc->setIgnoreTags($this->ignoreTags); 
     358                } 
     359                 
     360                if ($this->defaultPackageName) { 
     361                        $phpdoc->setDefaultPackageName($this->defaultPackageName); 
     362                } 
     363                 
     364                if ($this->defaultCategoryName) { 
     365                        $phpdoc->setDefaultCategoryName($this->defaultCategoryName); 
     366                } 
     367                 
     368                if ($this->pear) { 
     369                        $phpdoc->setPear($this->pear); 
    297370                } 
    298371                 
    …… 
    306379                } 
    307380                } 
    308                  
    309381                //print_r(implode(",", $filesToParse)); 
    310382                $phpdoc->setFilesToParse(implode(",", $filesToParse)); 
    311383                 
     384                 
     385                // append any files in filesets 
     386                $ricFiles = array(); 
     387                foreach($this->projDocFilesets as $fs) {                     
     388                $files = $fs->getDirectoryScanner($this->project)->getIncludedFiles(); 
     389                foreach($files as $filename) { 
     390                         $f = new PhingFile($fs->getDir($this->project), $filename); 
     391                         $ricFiles[] = $f->getAbsolutePath(); 
     392                } 
     393                } 
     394                $phpdoc->setRicFiles($ricFiles); 
     395                 
    312396        } 
    313397         

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

    r126 r158  
    495495  <li>mapping</li> 
    496496</ul> 
     497 
    497498<h2><a name="PHPDocumentorTask"></a>PHPDocumentorTask</h2> 
    498499<p>This task runs <a href="http://www.phpdoc.org/" 
    …… 
    514515      <td>title</td> 
    515516      <td>String</td> 
    516       <td> Title for browser window / package index. </td> 
    517       <td>n/a</td> 
    518       <td>No</td> 
    519     </tr> 
     517      <td>Title for browser window / package index. </td> 
     518      <td>n/a</td> 
     519      <td>No</td> 
     520    </tr> 
     521     
    520522    <tr> 
    521523      <td>destdir</td> 
    522524      <td>String</td> 
    523       <td> Destination directory for output files. </td> 
    524       <td>n/a</td> 
    525       <td>Yes</td> 
    526     </tr> 
    527     <tr> 
    528       <td>sourcepath</td> 
    529       <td>String</td> 
    530       <td> Specify where to find source files. </td> 
    531       <td>n/a</td> 
    532       <td>Yes</td> 
    533     </tr> 
    534     <tr> 
    535       <td>linksource</td> 
     525      <td>Destination directory for output files. </td> 
     526      <td>n/a</td> 
     527      <td rowspan="2">Yes</td> 
     528    </tr> 
     529     
     530    <tr> 
     531      <td>target</td> 
     532      <td>String</td> 
     533      <td>Alias of <em>destdir</em> ("target" is config param used by PhpDocumentor)</td> 
     534      <td>n/a</td> 
     535    </tr> 
     536 
     537    <tr> 
     538      <td>output</td> 
     539      <td>String</td> 
     540      <td>Output format (such as <em>HTML:Smarty:PHP</em>). </td> 
     541      <td>n/a</td> 
     542      <td>Yes</td> 
     543    </tr> 
     544      
     545    <tr> 
     546      <td>sourcecode</td> 
    536547      <td>Boolean</td> 
    537       <td> Generate hyperlinks to source files. </td> 
     548      <td>Generate syntax-highlighted sourcecode file for each file parsed?</td> 
    538549      <td>false</td> 
    539550      <td>No</td> 
    540551    </tr> 
    541     <tr> 
    542       <td>output</td> 
    543       <td>String</td> 
    544       <td> Output format (such as <em>HTML:Smarty:PHP</em>). </td> 
    545       <td>n/a</td> 
    546       <td>Yes</td> 
    547     </tr> 
     552     
     553    <tr> 
     554      <td>examplesdir</td> 
     555      <td>String</td> 
     556      <td>Path to directory in which to look for example documentation.</td> 
     557      <td>n/a</td> 
     558      <td>No</td> 
     559    </tr> 
     560     
    548561    <tr> 
    549562      <td>parseprivate</td> 
    …… 
    553566      <td>No</td> 
    554567    </tr> 
    555   </tbody> 
    556 </table> 
     568     
     569    <tr> 
     570      <td>javadocdesc</td> 
     571      <td>Boolean</td> 
     572      <td>JavaDoc-compliant description parsing.  Use on/off, default off (more flexibility)</td> 
     573      <td>false</td> 
     574      <td>No</td> 
     575    </tr> 
     576     
     577    <tr> 
     578      <td>quiet</td> 
     579      <td>Boolean</td> 
     580      <td>Suppress output to STDOUT.</td> 
     581      <td>false</td> 
     582      <td>No</td> 
     583    </tr> 
     584     
     585    <tr> 
     586      <td>packageoutput</td> 
     587      <td>String</td> 
     588      <td>Output documentation only for selected packages.  Use a comma-delimited list</td> 
     589      <td>n/a</td> 
     590      <td>No</td> 
     591    </tr> 
     592     
     593    <tr> 
     594      <td>ignoretags</td> 
     595      <td>String</td> 
     596      <td>Comma-separated list of tags to ignore (@package, @subpackage, @access and @ignore may not be ignored).</td> 
     597      <td>n/a</td> 
     598      <td>No</td> 
     599    </tr> 
     600     
     601    <tr> 
     602      <td>defaultpackagename</td> 
     603      <td>String</td> 
     604      <td>name to use for the default package.  If not specified, uses 'default'</td> 
     605      <td>n/a</td> 
     606      <td>No</td> 
     607    </tr> 
     608     
     609    <tr> 
     610      <td>defaultcategoryname</td> 
     611      <td>String</td> 
     612      <td>name to use for the default category.  If not specified, uses 'default'</td> 
     613      <td>n/a</td> 
     614      <td>No</td> 
     615    </tr> 
     616         
     617        <tr> 
     618      <td>pear</td> 
     619      <td>Boolean</td> 
     620      <td>Treat parse dirs as PEAR repository? (package is directory, _members are @access private)</td> 
     621      <td>false</td> 
     622      <td>No</td> 
     623    </tr> 
     624     
     625  </tbody> 
     626</table> 
     627 
     628<h3>Supported Nested Tags</h3> 
     629<ul> 
     630  <li>fileset - Files that should be included for parsing</li> 
     631  <li>projdocfileset - Files that should be treated as README/INSTALL/CHANGELOG files</li> 
     632</ul> 
     633 
    557634<h3>Examples</h3> 
    558 <pre>&lt;phpdoc title=&quot;Phing Documentation&quot; destdir=&quot;apidocs&quot; sourcepath=&quot;classes/phing&quot; output=&quot;HTML:Smarty:PHP&quot;/&gt;</pre> 
     635<pre> 
     636&lt;phpdoc title=&quot;Phing Documentation&quot; \ 
     637  destdir=&quot;apidocs&quot; 
     638  sourcepath=&quot;classes/phing&quot;  
     639  output=&quot;HTML:Smarty:PHP&quot;&gt; 
     640   &lt;fileset dir=&quot;./classes&quot; &gt; 
     641      &lt;include name=&quot;**/*.php&quot;&gt; 
     642   &lt;/fileset&gt; 
     643   &lt;projdocfileset dir=&quot;.&quot; &gt; 
     644      &lt;include name=&quot;README&quot;&gt; 
     645      &lt;include name=&quot;INSTALL&quot;&gt; 
     646      &lt;include name=&quot;CHANGELOG&quot;&gt; 
     647   &lt;/projdocfileset&gt; 
     648&lt;/phpdoc&gt; 
     649</pre> 
     650 
    559651<h2><a name="PhpLintTask"></a>PhpLintTask</h2> 
    560652<p>The <em>PhpLintTask</em> checks syntax (lint) on one or more PHP source code files.</p>