diff options
Diffstat (limited to 'buildscripts/phing/classes/phing/tasks/ext/phpdoc')
5 files changed, 1297 insertions, 0 deletions
diff --git a/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorErrorTracker.php b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorErrorTracker.php new file mode 100644 index 00000000..462b1d99 --- /dev/null +++ b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorErrorTracker.php @@ -0,0 +1,98 @@ +<?php +/** + * $Id: 73c919ab2044bf6582f52bd7ccb0184019d52f53 $ + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * This software consists of voluntary contributions made by many individuals + * and is licensed under the LGPL. For more information please see + * <http://phing.info>. + */ + +require_once 'PhpDocumentor/phpDocumentor/Errors.inc'; + +/** + * Phing subclass of the ErrorTracker class provided with PhpDocumentor to work around limitations in PhpDocumentor API. + * + * This class is necessary because PhpDocumentor does directly output errors and + * warnings occured during testing for undocumented elements to stdout. + * This class is injected globally to force PhpDocumentor to use phing's logging + * mechanism. + * + * Obviously this is far from ideal, but there's also no solution given the inflexibility of the + * PhpDocumentor design. + * + * @author Timo A. Hummel <privat@timohummel.com> @author felicitus + * @version $Id: 73c919ab2044bf6582f52bd7ccb0184019d52f53 $ + * @package phing.tasks.ext.phpdoc + */ +class PhingPhpDocumentorErrorTracker extends ErrorTracker { + + /* + * @var object Reference to the task we're called with + */ + private $task; + + /** + * Outputs a warning. This is an almost 1:1 copy from PhpDocumentor, + * we're just processing the warning text and send it to phing's logger. + * + * @param $num integer Number of parameters + * @return nothing + */ + function addWarning ($num) { + $a = array('', '', '', ''); + if (func_num_args()>1) { + for ($i=1;$i<func_num_args();$i++) { + $a[$i - 1] = func_get_arg($i); + } + } + + $message = sprintf($GLOBALS['phpDocumentor_warning_descrip'][$num], $a[0], $a[1], $a[2], $a[3]); + $this->task->log($message, Project::MSG_WARN); + + } + + /** + * Outputs an error. This is an almost 1:1 copy from PhpDocumentor, + * we're just processing the error text and send it to phing's logger. + * + * @param $num integer Number of parameters + * @return nothing + */ + + function addError ($num) { + $a = array('', '', '', ''); + if (func_num_args()>1) { + for ($i=1;$i<func_num_args();$i++) { + $a[$i - 1] = func_get_arg($i); + } + } + + $message = sprintf($GLOBALS['phpDocumentor_error_descrip'][$num], $a[0], $a[1], $a[2], $a[3]); + $this->task->log($message, Project::MSG_ERR); + + } + + /** + * Sets the task we're working with. This is necessary since we need to be + * able to call the method "log". + * + * @param object $task The task we're working with + * @return nothing + */ + public function setTask ($task) { + $this->task = $task; + } + +}
\ No newline at end of file diff --git a/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php new file mode 100644 index 00000000..62662b0b --- /dev/null +++ b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php @@ -0,0 +1,230 @@ +<?php +/** + * $Id: cde99d501839daf8c9dd9df61ee6cce7caad6b3e $ + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * This software consists of voluntary contributions made by many individuals + * and is licensed under the LGPL. For more information please see + * <http://phing.info>. + */ + +require_once 'PhpDocumentor/phpDocumentor/Setup.inc.php'; + +/** + * Phing subclass of the phpDocumentor_setup class provided with PhpDocumentor to work around limitations in PhpDocumentor API. + * + * This class is necessary because phpDocumentor_setup does not expose a complete API for setting configuration options. Because + * this class must directly modify some "private" GLOBAL(!) configuration variables, it is liable to break if the PhpDocumentor + * internal implementation changes. Obviously this is far from ideal, but there's also no solution given the inflexibility of the + * PhpDocumentor design. + * + * @author Hans Lellelid <hans@xmpl.org>@author hans + * @version $Id: cde99d501839daf8c9dd9df61ee6cce7caad6b3e $ + * @package phing.tasks.ext.phpdoc + */ +class PhingPhpDocumentorSetup extends phpDocumentor_setup { + + /** + * Constructs a new PhingPhpDocumentorSetup. + * + * @param string $configDir Directory in which to look for configuration files. + * @param object $task The task we're working with, so we can pass it on to the ErrorTracker + */ + public function __construct($configdir = null, $task) { + global $_phpDocumentor_cvsphpfile_exts, $_phpDocumentor_setting, $_phpDocumentor_phpfile_exts; + + $this->setup = new Io(); + $this->render = new phpDocumentor_IntermediateParser("Default Title"); + + $GLOBALS['_phpDocumentor_install_dir'] = $configdir; + $this->parseIni(); + + // These redundant-looking lines seem to actually make a difference. + // See: http://phing.info/trac/ticket/150 + $_phpDocumentor_phpfile_exts = $GLOBALS['_phpDocumentor_phpfile_exts']; + $_phpDocumentor_cvsphpfile_exts = $GLOBALS['_phpDocumentor_cvsphpfile_exts']; + + if (tokenizer_ext) { + $this->parse = new phpDocumentorTParser(); + } else { + $this->parse = new Parser(); + } + + $this->setMemoryLimit(); + + include_once 'phing/tasks/ext/phpdoc/PhingPhpDocumentorErrorTracker.php'; + + // Inject our own error tracker to PhpDocumentor + $GLOBALS['phpDocumentor_errors'] = new PhingPhpDocumentorErrorTracker; + $GLOBALS['phpDocumentor_errors']->setTask($task); + + } + + /** + * Set whether to generate sourcecode for each file parsed. + * + * This method exists as a hack because there is no API exposed for this in PhpDocumentor. + * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this + * is subject to break if PhpDocumentor internals changes. + * + * @param bool $b + */ + public function setGenerateSourcecode($b) { + global $_phpDocumentor_setting; + $_phpDocumentor_setting['sourcecode'] = (boolean) $b; + } + + /** + * Set an array of README/INSTALL/CHANGELOG file paths. + * + * This method exists as a hack because there is no API exposed for this in PhpDocumentor. + * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this + * is subject to break if PhpDocumentor internals changes. + * + * @param array $files Absolute paths to files. + */ + public function setRicFiles($files) { + global $_phpDocumentor_RIC_files; + $_phpDocumentor_RIC_files = $files; + } + + /** + * Set comma-separated list of tags to ignore. + * + * This method exists as a hack because there is no API exposed for this in PhpDocumentor. + * 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 $tags + */ + public function setIgnoreTags($tags) { + global $_phpDocumentor_setting; + $ignoretags = explode(',', $tags); + $ignoretags = array_map('trim', $ignoretags); + $tags = array(); + foreach($ignoretags as $tag) { + if (!in_array($tag,array('@global', '@access', '@package', '@ignore', '@name', '@param', '@return', '@staticvar', '@var'))) + $tags[] = $tag; + } + $_phpDocumentor_setting['ignoretags'] = $tags; + } + + /** + * Set whether to parse dirs as PEAR repos. + * + * This method exists as a hack because there is no API exposed for this in PhpDocumentor. + * Note that because we are setting a "private" GLOBAL(!!) config var with this value, this + * is subject to break if PhpDocumentor internals changes. + * + * @param bool $b + */ + public function setPear($b) { + global $_phpDocumentor_setting; + $_phpDocumentor_setting['pear'] = (boolean) $b; + } + + /** + * Set fullpath to directory to look in for examples. + * + * This method exists as a hack because there is no API exposed for this in PhpDocumentor. + * 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 $dir + */ + public function setExamplesDir($dir) { + global $_phpDocumentor_setting; + $_phpDocumentor_setting['examplesdir'] = $dir; + } + + /** + * Sets the default package name. + * + * This method exists as a hack because there is no API exposed for this in PhpDocumentor. + * 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 $name + */ + public function setDefaultPackageName($name) { + $GLOBALS['phpDocumentor_DefaultPackageName'] = trim($name); + } + + /** + * Sets the default category name. + * + * This method exists as a hack because there is no API exposed for this in PhpDocumentor. + * 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 $name + */ + public function setDefaultCategoryName($name) { + $GLOBALS['phpDocumentor_DefaultCategoryName'] = trim($name); + } + + /** + * Enables quiet mode. + * + * 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. + * + */ + public function setQuietMode() { + global $_phpDocumentor_setting; + $_phpDocumentor_setting['quiet'] = true; + parent::setQuietMode(); + } + + /** + * 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; + } + + /** + * Files to ignore + * + * @param string $sIgnore + */ + public function setIgnore($sIgnore) { + global $_phpDocumentor_setting; + $_phpDocumentor_setting['ignore'] = $sIgnore; + } +} diff --git a/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentor2Task.php b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentor2Task.php new file mode 100755 index 00000000..70fcc9e2 --- /dev/null +++ b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentor2Task.php @@ -0,0 +1,224 @@ +<?php +/* + * $Id: eaa494390770adc752097a412d63fb863482fd5d $ + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * This software consists of voluntary contributions made by many individuals + * and is licensed under the LGPL. For more information please see + * <http://phing.info>. + */ + +require_once 'phing/Task.php'; +require_once 'phing/system/io/FileOutputStream.php'; + +/** + * PhpDocumentor2 Task (http://www.phpdoc.org) + * Based on the DocBlox Task + * + * @author Michiel Rook <mrook@php.net> + * @version $Id: eaa494390770adc752097a412d63fb863482fd5d $ + * @since 2.4.10 + * @package phing.tasks.ext.phpdoc + */ +class PhpDocumentor2Task extends Task +{ + /** + * List of filesets + * @var FileSet[] + */ + private $filesets = array(); + + /** + * Destination/target directory + * @var PhingFile + */ + private $destDir = null; + + /** + * name of the template to use + * @var string + */ + private $template = "responsive"; + + /** + * Title of the project + * @var string + */ + private $title = ""; + + /** + * Force phpDocumentor to be quiet + * @var boolean + */ + private $quiet = true; + + /** + * Nested creator, adds a set of files (nested fileset attribute). + * + * @return FileSet + */ + public function createFileSet() + { + $num = array_push($this->filesets, new FileSet()); + return $this->filesets[$num-1]; + } + + /** + * Sets destination/target directory + * @param PhingFile $destDir + */ + public function setDestDir(PhingFile $destDir) + { + $this->destDir = $destDir; + } + + /** + * Convenience setter (@see setDestDir) + * @param PhingFile $output + */ + public function setOutput(PhingFile $output) + { + $this->destDir = $output; + } + + /** + * Sets the template to use + * @param strings $template + */ + public function setTemplate($template) + { + $this->template = (string) $template; + } + + /** + * Sets the title of the project + * @param strings $title + */ + public function setTitle($title) + { + $this->title = (string) $title; + } + + /** + * Forces phpDocumentor to be quiet + * @param boolean $quiet + */ + public function setQuiet($quiet) + { + $this->quiet = (boolean) $quiet; + } + + /** + * Finds and initializes the phpDocumentor installation + */ + private function initializePhpDocumentor() + { + $phpDocumentorPath = null; + + foreach (explode(PATH_SEPARATOR, get_include_path()) as $path) { + $testPhpDocumentorPath = $path . DIRECTORY_SEPARATOR . 'phpDocumentor' . DIRECTORY_SEPARATOR . 'src'; + + if (file_exists($testPhpDocumentorPath)) { + $phpDocumentorPath = $testPhpDocumentorPath; + } + } + + if (empty($phpDocumentorPath)) { + throw new BuildException("Please make sure PhpDocumentor 2 is installed and on the include_path.", $this->getLocation()); + } + + set_include_path($phpDocumentorPath . PATH_SEPARATOR . get_include_path()); + + require_once $phpDocumentorPath . '/phpDocumentor/Bootstrap.php'; + + $bootstrap = phpDocumentor_Bootstrap::createInstance(); + + $autoloader = $bootstrap->registerAutoloader(); + + if ($this->quiet) { + phpDocumentor_Core_Abstract::config()->logging->level = 'quiet'; + } else { + phpDocumentor_Core_Abstract::config()->logging->level = 'debug'; + } + + $bootstrap->registerPlugins($autoloader); + } + + /** + * Build a list of files (from the fileset elements) + * and call the phpDocumentor parser + * + * @return string + */ + private function parseFiles() + { + $parser = new phpDocumentor_Parser(); + + //Only initialize the dispatcher when not already done + if (is_null(phpDocumentor_Parser_Abstract::$event_dispatcher)) { + phpDocumentor_Parser_Abstract::$event_dispatcher = new sfEventDispatcher(); + } + $parser->setTitle($this->title); + + $paths = array(); + + // filesets + foreach ($this->filesets as $fs) { + $ds = $fs->getDirectoryScanner($this->project); + $dir = $fs->getDir($this->project); + $srcFiles = $ds->getIncludedFiles(); + + foreach ($srcFiles as $file) { + $paths[] = $dir . FileSystem::getFileSystem()->getSeparator() . $file; + } + } + + $this->log("Will parse " . count($paths) . " file(s)", Project::MSG_VERBOSE); + + $files = new phpDocumentor_Parser_Files(); + $files->addFiles($paths); + + $parser->setPath($files->getProjectRoot()); + + return $parser->parseFiles($files); + } + + /** + * Task entry point + * @see Task::main() + */ + public function main() + { + if (empty($this->destDir)) { + throw new BuildException("You must supply the 'destdir' attribute", $this->getLocation()); + } + + if (empty($this->filesets)) { + throw new BuildException("You have not specified any files to include (<fileset>)", $this->getLocation()); + } + + $this->initializePhpDocumentor(); + + $xml = $this->parseFiles(); + + $this->log("Transforming...", Project::MSG_VERBOSE); + + $transformer = new phpDocumentor_Transformer(); + $transformer->setTemplatesPath(phpDocumentor_Core_Abstract::config()->paths->templates); + $transformer->setTemplates($this->template); + $transformer->setSource($xml); + $transformer->setTarget($this->destDir->getAbsolutePath()); + $transformer->execute(); + } +}
\ No newline at end of file diff --git a/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentorExternalTask.php b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentorExternalTask.php new file mode 100755 index 00000000..fb2a0b2b --- /dev/null +++ b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentorExternalTask.php @@ -0,0 +1,265 @@ +<?php + +/** + * $Id: 6a6c740651bb91c9854fcdf0cb1d7e768b84f805 $ + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * This software consists of voluntary contributions made by many individuals + * and is licensed under the LGPL. For more information please see + * <http://phing.info>. + */ + +require_once 'phing/tasks/ext/phpdoc/PhpDocumentorTask.php'; + +/** + * 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 <mrook@php.net> + * @author Markus Fischer <markus@fischer.name> + * @version $Id: 6a6c740651bb91c9854fcdf0cb1d7e768b84f805 $ + * @package phing.tasks.ext.phpdoc + */ +class PhpDocumentorExternalTask extends PhpDocumentorTask +{ + /** + * The path to the executable for phpDocumentor + */ + protected $programPath = 'phpdoc'; + + protected $sourcepath = NULL; + + /** + * @var bool ignore symlinks to other files or directories + */ + protected $ignoresymlinks = false; + + /** + * Sets the path to the phpDocumentor executable + */ + public function setProgramPath($programPath) + { + $this->programPath = $programPath; + } + + /** + * Returns the path to the phpDocumentor executable + */ + public function getProgramPath() + { + return $this->programPath; + } + + /** + * Set the source path. A directory or a comma separate list of directories. + */ + public function setSourcepath($sourcepath) + { + $this->sourcepath = $sourcepath; + } + + /** + * Ignore symlinks to other files or directories. + * + * @param bool $bSet + */ + public function setIgnoresymlinks($bSet) { + $this->ignoresymlinks = $bSet; + } + + /** + * Main entrypoint of the task + */ + public function main() + { + $this->validate(); + $arguments = join(' ', $this->constructArguments()); + + $this->log("Running phpDocumentor..."); + + exec($this->programPath . " " . $arguments, $output, $return); + + if ($return != 0) + { + throw new BuildException("Could not execute phpDocumentor: " . implode(' ', $output)); + } + + foreach($output as $line) + { + if(strpos($line, 'ERROR') !== false) + { + $this->log($line, Project::MSG_ERR); + continue; + } + + $this->log($line, Project::MSG_VERBOSE); + } + } + + /** + * Constructs an argument string for phpDocumentor + * @return array + */ + protected function constructArguments() + { + $aArgs = array(); + if ($this->title) + { + $aArgs[] = '--title "' . $this->title . '"'; + } + + if ($this->destdir) + { + $aArgs[] = '--target "' . $this->destdir->getAbsolutePath() . '"'; + } + + if ($this->sourcepath) + { + $aArgs[] = '--directory "' . $this->sourcepath . '"'; + } + + if ($this->output) + { + $aArgs[] = '--output ' . $this->output; + } + + if ($this->linksource) + { + $aArgs[] = '--sourcecode on'; + } + + if ($this->parseprivate) + { + $aArgs[] = '--parseprivate on'; + } + + if ($this->ignore) + { + $aArgs[] = '--ignore ' . $this->ignore; + } + + // 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'; + } + + 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 (<fileset> or sourcepath attribute) for phpdoc.", + $this->getLocation()); + } + if ($this->configdir) { + $this->log('Ignoring unsupported configdir-Attribute', + Project::MSG_VERBOSE); + } + } +}; + + + diff --git a/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentorTask.php b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentorTask.php new file mode 100755 index 00000000..e4ae363a --- /dev/null +++ b/buildscripts/phing/classes/phing/tasks/ext/phpdoc/PhpDocumentorTask.php @@ -0,0 +1,480 @@ +<?php + +/** + * $Id: 23a04ddae9cad46198e15081a0fb44354135b1c8 $ + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * This software consists of voluntary contributions made by many individuals + * and is licensed under the LGPL. For more information please see + * <http://phing.info>. + */ + +require_once 'phing/Task.php'; + +/** + * Task to run PhpDocumentor. + * + * @author Hans Lellelid <hans@xmpl.org> + * @author Michiel Rook <mrook@php.net> + * @version $Id: 23a04ddae9cad46198e15081a0fb44354135b1c8 $ + * @package phing.tasks.ext.phpdoc + */ +class PhpDocumentorTask extends Task +{ + + /** + * @var string Title for browser window / package index. + */ + protected $title; + + /** + * @var PhingFile The target directory for output files. + */ + protected $destdir; + + /** + * @var array FileSet[] Filesets for files to parse. + */ + protected $filesets = array(); + + /** + * @var array FileSet[] Project documentation (README/INSTALL/CHANGELOG) files. + */ + protected $projDocFilesets = array(); + + /** + * @var string Package output format. + */ + protected $output; + + /** + * @var boolean Whether to generate sourcecode for each file parsed. + */ + protected $linksource = false; + + /** + * @var boolean Whether to parse private members. + */ + protected $parsePrivate = false; + + /** + * @var boolean Whether to use javadoc descriptions (more primitive). + */ + protected $javadocDesc = false; + + /** + * @var PhingFile Base directory for locating template files. + */ + protected $templateBase; + + /** + * @var boolean Wheter to suppress output. + */ + protected $quiet = false; + + /** + * @var string Comma-separated list of packages to output. + */ + protected $packages; + + /** + * @var string Comma-separated list of tags to ignore. + */ + protected $ignoreTags; + + /** + * @var string Default package name. + */ + protected $defaultPackageName; + + /** + * @var string Default category name. + */ + protected $defaultCategoryName; + + /** + * @var PhingFile Directory in which to look for examples. + */ + protected $examplesDir; + + /** + * @var PhingFile Directory in which to look for configuration files. + */ + protected $configDir; + + /** + * @var boolean Whether to parse as a PEAR repository. + */ + 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 = ''; + + /** + * @var string files to ignore + */ + protected $ignore = ''; + + /** + * Set the title for the generated documentation + */ + public function setTitle($title) { + $this->title = $title; + } + + /** + * Set the destination directory for the generated documentation + */ + public function setDestdir(PhingFile $destdir) { + $this->destdir = $destdir; + } + + /** + * Alias for {@link setDestdir()}. + * @see setDestdir() + */ + public function setTarget(PhingFile $destdir) { + $this->setDestdir($destdir); + } + + /** + * Set the output format (e.g. HTML:Smarty:PHP). + * @param string $output + */ + public function setOutput($output) { + $this->output = $output; + } + + /** + * Set whether to generate sourcecode for each file parsed + * @param boolean + */ + public function setSourcecode($b) { + $this->setLinksource($b); + } + + /** + * Set whether to generate sourcecode for each file parsed + * @param boolean + */ + public function setLinksource($b) { + $this->linksource = $b; + } + + /** + * Set whether to suppress output. + * @param boolean $b + */ + public function setQuiet($b) { + $this->quiet = $b; + } + + /** + * Should private members/classes be documented + * @param boolean + */ + public function setParseprivate($parseprivate) { + $this->parsePrivate = $parseprivate; + } + + /** + * Whether to use javadoc descriptions (more primitive). + * @param boolean + */ + public function setJavadocdesc($javadoc) { + $this->javadocDesc = $javadoc; + } + + /** + * Set (comma-separated) list of packages to output. + * + * @param string $packages + */ + public function setPackageoutput($packages) { + $this->packages = $packages; + } + + /** + * Set (comma-separated) list of tags to ignore. + * + * @param string $tags + */ + public function setIgnoretags($tags) { + $this->ignoreTags = $tags; + } + + /** + * Set a directory to search for examples in. + * @param PhingFile $d + */ + public function setExamplesdir(PhingFile $d) { + $this->examplesDir = $d; + } + + /** + * Set a directory to search for configuration files in. + * @param PhingFile $d + */ + public function setConfigdir(PhingFile $d) { + $this->configDir = $d; + } + + /** + * Sets the default package name. + * @param string $name + */ + public function setDefaultpackagename($name) { + $this->defaultPackageName = $name; + } + + /** + * Sets the default category name. + * @param string $name + */ + public function setDefaultcategoryname($name) { + $this->defaultCategoryName = $name; + } + + /** + * Set whether to parse as PEAR repository. + * @param boolean $b + */ + public function setPear($b) { + $this->pear = $b; + } + + /** + * Creates a FileSet. + * @return FileSet + */ + public function createFileset() { + $num = array_push($this->filesets, new FileSet()); + return $this->filesets[$num-1]; + } + + /** + * Creates a readme/install/changelog fileset. + * @return FileSet + */ + public function createProjdocfileset() { + $num = array_push($this->projDocFilesets, new FileSet()); + 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; + } + + /** + * Set files to ignore + * @param string $sIgnore + */ + public function setIgnore($sIgnore) { + $this->ignore = $sIgnore; + } + + /** + * Searches include_path for PhpDocumentor install and adjusts include_path appropriately. + * @throws BuildException - if unable to find PhpDocumentor on include_path + */ + protected function findPhpDocumentorInstall() + { + $found = null; + foreach(explode(PATH_SEPARATOR, get_include_path()) as $path) { + $testpath = $path . DIRECTORY_SEPARATOR . 'PhpDocumentor'; + if (file_exists($testpath)) { + $found = $testpath; + break; + } + } + if (!$found) { + throw new BuildException("PhpDocumentor task depends on PhpDocumentor being installed and on include_path.", $this->getLocation()); + } + // otherwise, adjust the include_path to path to include the PhpDocumentor directory ... + set_include_path(get_include_path() . PATH_SEPARATOR . $found); + include_once ("phpDocumentor/Setup.inc.php"); + if (!class_exists('phpDocumentor_setup')) { + throw new BuildException("Error including PhpDocumentor setup class file."); + } + } + + /** + * Main entrypoint of the task + * Loads the necessary environment for running PhpDoc, then runs PhpDoc + * + * @throws BuildException - if the phpdoc classes can't be loaded. + */ + function main() + { + $this->findPhpDocumentorInstall(); + include_once 'phing/tasks/ext/phpdoc/PhingPhpDocumentorSetup.php'; + + $this->validate(); + $configdir = $this->configDir ? $this->configDir->getAbsolutePath() : null; + $phpdoc = new PhingPhpDocumentorSetup($configdir, $this); + $this->setPhpDocumentorOptions($phpdoc); + //$phpdoc->readCommandLineSettings(); + $phpdoc->setupConverters($this->output); + $phpdoc->createDocs(); + } + + /** + * Validates that necessary minimum options have been set. + * @throws BuildException if validation doesn't pass + */ + 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)) { + throw new BuildException("You have not specified any files to include (<fileset>) for phpdoc.", $this->getLocation()); + } + } + + /** + * Sets the options on the passed-in phpdoc setup object. + * @param PhingPhpDocumentorSetup $phpdoc + */ + protected function setPhpDocumentorOptions(PhingPhpDocumentorSetup $phpdoc) + { + + // Title MUST be set first ... (because it re-initializes the internal state of the PhpDocu renderer) + if ($this->title) { + $phpdoc->setTitle($this->title); + } + + if ($this->parsePrivate) { + $phpdoc->setParsePrivate(); + } + + if ($this->javadocDesc) { + $phpdoc->setJavadocDesc(); + } + + if ($this->quiet) { + $phpdoc->setQuietMode(); + } + + if ($this->destdir) { + $phpdoc->setTargetDir($this->destdir->getAbsolutePath()); + } + + if ($this->packages) { + $phpdoc->setPackageOutput($this->packages); + } + + if ($this->templateBase) { + $phpdoc->setTemplateBase($this->templateBase->getAbsolutePath()); + } + + if ($this->linksource) { + $phpdoc->setGenerateSourcecode($this->linksource); + } + + if ($this->examplesDir) { + $phpdoc->setExamplesDir($this->examplesDir->getAbsolutePath()); + } + + if ($this->ignoreTags) { + $phpdoc->setIgnoreTags($this->ignoreTags); + } + + if ($this->defaultPackageName) { + $phpdoc->setDefaultPackageName($this->defaultPackageName); + } + + if ($this->defaultCategoryName) { + $phpdoc->setDefaultCategoryName($this->defaultCategoryName); + } + + if ($this->pear) { + $phpdoc->setPear($this->pear); + } + + if ($this->ignore) { + $phpdoc->setIgnore($this->ignore); + } + + // 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(); + } + } + //print_r(implode(",", $filesToParse)); + $phpdoc->setFilesToParse(implode(",", $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->getName(); + } + } + $phpdoc->setRicFiles($ricFiles); + + if ($this->undocumentedelements) { + $phpdoc->setUndocumentedelements($this->undocumentedelements); + } + + if ($this->customtags) { + $phpdoc->setCustomtags($this->customtags); + } + } +} |