Index: classes/phing/tasks/ext/phpdoc/PhpDocumentorTask.php =================================================================== --- classes/phing/tasks/ext/phpdoc/PhpDocumentorTask.php (revision 338) +++ classes/phing/tasks/ext/phpdoc/PhpDocumentorTask.php (working copy) @@ -36,87 +36,100 @@ /** * @var string Title for browser window / package index. */ - private $title; + protected $title; /** * @var PhingFile The target directory for output files. */ - private $destdir; + protected $destdir; /** * @var array FileSet[] Filesets for files to parse. */ - private $filesets = array(); + protected $filesets = array(); /** * @var array FileSet[] Project documentation (README/INSTALL/CHANGELOG) files. */ - private $projDocFilesets = array(); + protected $projDocFilesets = array(); /** * @var string Package output format. */ - private $output; + protected $output; /** * @var boolean Whether to generate sourcecode for each file parsed. */ - private $linksource = false; + protected $linksource = false; /** * @var boolean Whether to parse private members. */ - private $parsePrivate = false; + protected $parsePrivate = false; /** * @var boolean Whether to use javadoc descriptions (more primitive). */ - private $javadocDesc = false; + protected $javadocDesc = false; /** * @var PhingFile Base directory for locating template files. */ - private $templateBase; + protected $templateBase; /** * @var boolean Wheter to suppress output. */ - private $quiet = false; + protected $quiet = false; /** * @var string Comma-separated list of packages to output. */ - private $packages; + protected $packages; /** * @var string Comma-separated list of tags to ignore. */ - private $ignoreTags; + protected $ignoreTags; /** * @var string Default package name. */ - private $defaultPackageName; + protected $defaultPackageName; /** * @var string Default category name. */ - private $defaultCategoryName; + protected $defaultCategoryName; /** * @var PhingFile Directory in which to look for examples. */ - private $examplesDir; + protected $examplesDir; /** * @var PhingFile Directory in which to look for configuration files. */ - private $configDir; + protected $configDir; /** * @var boolean Whether to parse as a PEAR repository. */ - private $pear = false; + protected $pear = false; + + /** + * @var boolean Control whether or not warnings will be shown for + * undocumented elements. Useful for identifying classes and + * methods that haven't yet been documented. + */ + protected $undocumentedelements = false; + + /** + * @var string custom tags, will be recognized and put in tags[] instead of + * unknowntags[]. + */ + protected $customtags = ''; /** * Set the title for the generated documentation @@ -256,7 +269,36 @@ return $this->projDocFilesets[$num-1]; } + /** + * Control whether or not warnings will be shown for undocumented elements. + * Useful for identifying classes and methods that haven't yet been + * documented. + * @param boolean $b + */ + public function setUndocumentedelements($b) { + $this->undocumentedelements = $b; + } + /** + * custom tags, will be recognized and put in tags[] instead of + * unknowntags[]. + * + * @param string $sCustomtags + */ + public function setCustomtags($sCustomtags) { + $this->customtags = $sCustomtags; + } + + /** + * Set base location of all templates for this parse. + * + * @param PhingFile $destdir + */ + public function setTemplateBase(PhingFile $oTemplateBase) { + $this->templateBase = $oTemplateBase; + } + + /** * Searches include_path for PhpDocumentor install and adjusts include_path appropriately. * @throws BuildException - if unable to find PhpDocumentor on include_path */ @@ -406,7 +448,13 @@ } } $phpdoc->setRicFiles($ricFiles); - + + if ($this->undocumentedelements) { + $phpdoc->setUndocumentedelements($this->undocumentedelements); + } + + if ($this->customtags) { + $phpdoc->setCustomtags($this->customtags); + } } - } Index: classes/phing/tasks/ext/phpdoc/PhpDocumentorExternalTask.php =================================================================== --- classes/phing/tasks/ext/phpdoc/PhpDocumentorExternalTask.php (revision 338) +++ classes/phing/tasks/ext/phpdoc/PhpDocumentorExternalTask.php (working copy) @@ -20,41 +20,38 @@ * . */ -require_once 'phing/Task.php'; +require_once 'phing/tasks/ext/phpdoc/PhpDocumentorTask.php'; /** - * Task to run phpDocumentor. + * Task to run phpDocumentor with an external process * * This classes uses the commandline phpdoc script to build documentation. + * Use this task instead of the PhpDocumentorTask when you've a clash with the + * Smarty libraries. * * @author Michiel Rook + * @author Markus Fischer * @version $Id$ * @package phing.tasks.ext.phpdoc - * @deprecated This task is being replaced by the new PhpDocumentorTask */ -class PhpDocumentorExternalTask extends Task +class PhpDocumentorExternalTask extends PhpDocumentorTask { /** * The path to the executable for phpDocumentor */ - private $programPath = 'phpdoc'; + protected $programPath = 'phpdoc'; - private $title = "Default Title"; + protected $sourcepath = NULL; - private $destdir = "."; + /** + * @var bool ignore symlinks to other files or directories + */ + protected $ignoresymlinks = false; - private $sourcepath = NULL; - - private $output = ""; - - private $linksource = false; - - private $parseprivate = false; - /** * Sets the path to the phpDocumentor executable */ - function setProgramPath($programPath) + public function setProgramPath($programPath) { $this->programPath = $programPath; } @@ -62,72 +59,35 @@ /** * Returns the path to the phpDocumentor executable */ - function getProgramPath() + public function getProgramPath() { return $this->programPath; } /** - * Set the title for the generated documentation + * Set the source path. A directory or a comma separate list of directories. */ - function setTitle($title) + public function setSourcepath($sourcepath) { - $this->title = $title; + $this->sourcepath = $sourcepath; } - /** - * Set the destination directory for the generated documentation - */ - function setDestdir($destdir) - { - $this->destdir = $destdir; - } + /** + * Ignore symlinks to other files or directories. + * + * @param bool $bSet + */ + public function setIgnoresymlinks($bSet) { + $this->ignoresymlinks = $bSet; + } /** - * Set the source path - */ - function setSourcepath(Path $sourcepath) - { - if ($this->sourcepath === NULL) - { - $this->sourcepath = $sourcepath; - } - else - { - $this->sourcepath->append($sourcepath); - } - } - - /** - * Set the output type - */ - function setOutput($output) - { - $this->output = $output; - } - - /** - * Should sources be linked in the generated documentation - */ - function setLinksource($linksource) - { - $this->linksource = $linksource; - } - - /** - * Should private members/classes be documented - */ - function setParseprivate($parseprivate) - { - $this->parseprivate = $parseprivate; - } - - /** * Main entrypoint of the task */ - function main() + public function main() { - $arguments = $this->constructArguments(); + $this->validate(); + $arguments = join(' ', $this->constructArguments()); $this->log("Running phpDocumentor..."); @@ -152,43 +112,149 @@ /** * Constructs an argument string for phpDocumentor + * @return array */ - private function constructArguments() + protected function constructArguments() { - $arguments = "-q on "; - + $aArgs = array(); if ($this->title) { - $arguments.= "-ti \"" . $this->title . "\" "; + $aArgs[] = '--title "' . $this->title . '"'; } if ($this->destdir) { - $arguments.= "-t \"" . $this->destdir . "\" "; + $aArgs[] = '--target "' . $this->destdir->getAbsolutePath() . '"'; } - if ($this->sourcepath !== NULL) + if ($this->sourcepath) { - $arguments.= "-d \"" . $this->sourcepath->__toString() . "\" "; + $aArgs[] = '--directory "' . $this->sourcepath . '"'; } if ($this->output) { - $arguments.= "-o " . $this->output . " "; + $aArgs[] = '--output ' . $this->output; } if ($this->linksource) { - $arguments.= "-s on "; + $aArgs[] = '--sourcecode on'; } if ($this->parseprivate) { - $arguments.= "-pp on "; + $aArgs[] = '--parseprivate on'; } - return $arguments; + // append any files in filesets + $filesToParse = array(); + foreach($this->filesets as $fs) { + $files = $fs->getDirectoryScanner($this->project)->getIncludedFiles(); + foreach($files as $filename) { + $f = new PhingFile($fs->getDir($this->project), $filename); + $filesToParse[] = $f->getAbsolutePath(); + } + } + if (count($filesToParse) > 0) { + $aArgs[] = '--filename "' . join(',', $filesToParse) . '"'; + } + + // append any files in filesets + $ricFiles = array(); + foreach($this->projDocFilesets as $fs) { + $files = $fs->getDirectoryScanner($this->project)->getIncludedFiles(); + foreach($files as $filename) { + $f = new PhingFile($fs->getDir($this->project), $filename); + $ricFiles[] = $f->getAbsolutePath(); + } + } + if (count($ricFiles) > 0) { + $aArgs[] = '--readmeinstallchangelog "' . + join(',', $ricFiles) . '"'; + } + + if ($this->javadocDesc) { + $aArgs[] = '--javadocdesc on'; + } + + if ($this->quiet) { + $aArgs[] = '--quiet on'; + } + + if ($this->packages) { + $aArgs[] = '--packageoutput "' . $this->packages . '"'; + } + + if ($this->ignoreTags) { + $aArgs[] = '--ignore-tags "' . $this->ignoreTags . '"'; + } + + if ($this->defaultCategoryName) { + $aArgs[] = '--defaultcategoryname "' . $this->defaultCategoryName . + '"'; + } + + if ($this->examplesDir) { + $aArgs[] = '--examplesdir "' . $this->examplesDir->getAbsolutePath() + . '"'; + } + + if ($this->templateBase) { + $aArgs[] = '--templatebase "' . $this->templateBase->getAbsolutePath() + . '"'; + } + + if ($this->pear) { + $aArgs[] = '--pear on'; + } + + if ($this->undocumentedelements) { + $aArgs[] = '--undocumentedelements on'; + } + + if ($this->customtags) { + $aArgs[] = '--customtags "' . $this->customtags . '"'; + } + + if ($this->ignoresymlinks) { + $aArgs[] = '--ignoresymlinks on'; + } + + var_dump($aArgs);exit; + return $aArgs; } + + /** + * Override PhpDocumentorTask::init() because they're specific to the phpdoc + * API which we don't use. + */ + public function init() { + } + + /** + * Validates that necessary minimum options have been set. Based on + * PhpDocumentorTask::validate(). + */ + protected function validate() { + if (!$this->destdir) { + throw new BuildException("You must specify a destdir for phpdoc.", + $this->getLocation()); + } + if (!$this->output) { + throw new BuildException("You must specify an output format for " . + "phpdoc (e.g. HTML:frames:default).", $this->getLocation()); + } + if (empty($this->filesets) && !$this->sourcepath) { + throw new BuildException("You have not specified any files to " . + "include ( or sourcepath attribute) for phpdoc.", + $this->getLocation()); + } + if ($this->configdir) { + $this->log('Ignoring unsupported configdir-Attribute', + Project::MSG_VERBOSE); + } + } }; Index: classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php =================================================================== --- classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php (revision 338) +++ classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php (working copy) @@ -172,5 +172,32 @@ $_phpDocumentor_setting['quiet'] = true; parent::setQuietMode(); } - -} \ No newline at end of file + + /** + * Control whether or not warnings will be shown for undocumented elements. + * Useful for identifying classes and methods that haven't yet been + * documented. + * + * @param bool $bEnable + */ + public function setUndocumentedelements($bEnable) { + $this->render->setUndocumentedElementWarningsMode($bEnable); + } + + /** + * custom tags, will be recognized and put in tags[] instead of + * unknowntags[] + * + * This method exists as a hack because the API exposed for this method in + * PhpDocumentor doesn't work correctly. + * + * Note that because we are setting a "private" GLOBAL(!!) config var with + * this value, this is subject to break if PhpDocumentor internals changes. + * + * @param string $sCustomtags + */ + public function setCustomtags($sCustomtags) { + global $_phpDocumentor_setting; + $_phpDocumentor_setting['customtags'] = $sCustomtags; + } +}