Projects / luoyu's fork of Api Generator

diff --git a/controllers/components/documentor.php b/controllers/components/documentor.php index 5ea0e46..738cf42 100644 --- a/controllers/components/documentor.php +++ b/controllers/components/documentor.php @@ -42,6 +42,18 @@ class DocumentorComponent extends Object { **/ protected $_extractor; /** + * storage for defined classes + * + * @var array + **/ + protected $_definedClasses = array(); +/** + * storage for defined functions + * + * @var array + **/ + protected $_definedFunctions = array(); +/** * initialize Callback * * @return void @@ -50,8 +62,6 @@ class DocumentorComponent extends Object { $this->controller = $controller; } /** - * loadClass - * * Loads the documentation extractor for a given classname. * * @param string $name Name of class to load. @@ -62,13 +72,11 @@ class DocumentorComponent extends Object { $this->_extractor = Introspector::getReflector($type, $name); } /** - * getClassDocs - * * Gets the parsed docs from the Extractor * * @return array Array with all the extracted docs. **/ - public function getClassDocs() { + public function getDocs() { $this->_extractor->getAll(); return $this->_extractor; } @@ -83,8 +91,6 @@ class DocumentorComponent extends Object { $controller->set('excludeClasses', Configure::read('ApiGenerator.excludeClasses')); } /** - * getExtractor - * * Get the documentor extractor instance * * @access public @@ -94,8 +100,6 @@ class DocumentorComponent extends Object { return $this->_extractor; } /** - * loadFile - * * Load A File and extract docs for all classes contained in that file * * @param string $fullPath FullPath of the file you want to load. @@ -113,35 +117,44 @@ class DocumentorComponent extends Object { $baseClass['View'] = 'View'; } $this->_importBaseClasses($baseClass); - - $addedClasses = $this->_findClassesInFile($filePath); + $this->_getDefinedObjects(); + $addedClasses = $this->_findObjectsInFile($filePath); $docs = array(); foreach ($addedClasses as $class) { $this->loadExtractor('class', $class); if ($this->getExtractor()->getFileName() == $filePath) { - $docs[$class] = $this->getClassDocs(); + $docs[$class] = $this->getDocs(); } } return $docs; } /** + * gets the currently defined functions and classes + * so comparisons to new files can be made + * + * @return void + **/ + protected function _getDefinedObjects() { + $this->_definedClasses = get_declared_classes(); + $this->_definedFunctions = get_defined_functions(); + } +/** * _getClassNamesFromFile * * Fetches the class names contained in the target file. * * @return array **/ - protected function _findClassesInFile($filePath) { + protected function _findObjectsInFile($filePath) { $includedFiles = get_included_files(); if (in_array($filePath, $includedFiles)) { $newClasses = $this->_parseClassNamesInFile($filePath); } else { - $currentClassList = get_declared_classes(); ob_start(); include_once $filePath; ob_clean(); - $newClasses = array_diff(get_declared_classes(), $currentClassList); + $newClasses = array_diff(get_declared_classes(), $this->_definedClasses); } return $newClasses; } diff --git a/tests/cases/vendors/class_documentor.test.php b/tests/cases/vendors/class_documentor.test.php index d32eb06..5e8fbea 100644 --- a/tests/cases/vendors/class_documentor.test.php +++ b/tests/cases/vendors/class_documentor.test.php @@ -82,7 +82,7 @@ class DocumentExtractorTestCase extends CakeTestCase { 'fileName' => __FILE__, 'classDescription' => 'class SimpleDocumentorSubjectClass extends stdClass implements Countable ', 'comment' => array ( - 'desc' => "SimpleDocumentorSubjectClass\n\nA simple class to test ClassInfo introspection", + 'description' => "SimpleDocumentorSubjectClass\n\nA simple class to test ClassInfo introspection", 'tags' => array ( 'package' => 'this is my package', 'another-tag' => 'long value' @@ -106,7 +106,7 @@ class DocumentExtractorTestCase extends CakeTestCase { 'name' => '_protectedVar', 'declaredInClass' => 'SimpleDocumentorSubjectClass', 'comment' => array( - 'desc' => 'This var is protected', + 'description' => 'This var is protected', 'tags' => array( 'var' => 'string' ) @@ -116,7 +116,7 @@ class DocumentExtractorTestCase extends CakeTestCase { 'name' => 'publicVar', 'declaredInClass' => 'SimpleDocumentorSubjectClass', 'comment' => array( - 'desc' => 'This var is public', + 'description' => 'This var is public', 'tags' => array( 'var' => 'string' ) @@ -127,7 +127,7 @@ class DocumentExtractorTestCase extends CakeTestCase { 'name' => 'publicStatic', 'declaredInClass' => 'SimpleDocumentorSubjectClass', 'comment' => array( - 'desc' => 'This var is public static', + 'description' => 'This var is public static', 'tags' => array( 'var' => 'string' ) @@ -150,7 +150,7 @@ class DocumentExtractorTestCase extends CakeTestCase { array( 'name' => 'count', 'comment' => array( - 'desc' => "count\n\nImplementation of Countable interface", + 'description' => "count\n\nImplementation of Countable interface", 'tags' => array( 'access' => 'public', 'return' => 'integer' @@ -165,7 +165,7 @@ class DocumentExtractorTestCase extends CakeTestCase { array( 'name' => 'something', 'comment' => array( - 'desc' => "something\n\ndoes something", + 'description' => "something\n\ndoes something", 'tags' => array( 'access' => 'public', 'return' => 'integer' @@ -195,7 +195,7 @@ class DocumentExtractorTestCase extends CakeTestCase { array( 'name' => 'goGo', 'comment' => array( - 'desc' => "goGo\n\ndoes lots of cool things", + 'description' => "goGo\n\ndoes lots of cool things", 'tags' => array( 'return' => 'void' ) diff --git a/tests/cases/vendors/function_documentor.test.php b/tests/cases/vendors/function_documentor.test.php index 28f0fb6..ca0ff70 100644 --- a/tests/cases/vendors/function_documentor.test.php +++ b/tests/cases/vendors/function_documentor.test.php @@ -1,6 +1,92 @@ <?php App::import('Vendor', 'ApiGenerator.FunctionDocumentor'); - +/** + * my_random_test_function + * + * @param string $param this is a param + * @param string $one this is one + * @param string $two this is two + * @return void + */ +function my_random_test_function($param, $one = 'foo', $two = 'param') { + +} +/** + * FunctionDocumentor Test Case + * + * @package default + * @author Mark Story + */ class FunctionDocumentorTestCase extends CakeTestCase { - +/** + * testInfo Getting + * + * @return void + **/ + function testGetInfo() { + $Docs = new FunctionDocumentor('my_random_test_function'); + $result = $Docs->getInfo(); + $expected = array( + 'name' => 'my_random_test_function', + 'declaredInFile' => __FILE__, + 'startLine' => 11, + 'endLine' => 13, + 'comment' => array( + 'description' => 'my_random_test_function', + 'tags' => array( + 'return' => 'void', + 'param' => array( + 'param' => array( + 'type' => 'string', + 'description' => 'this is a param', + ), + 'one' => array( + 'type' => 'string', + 'description' => 'this is one', + ), + 'two' => array( + 'type' => 'string', + 'description' => 'this is two', + ) + ) + ) + ), + 'internal' => false + ); + $this->assertEqual($result, $expected); + $this->assertEqual($Docs->info, $expected); + } +/** + * test getParameters + * + * @return void + **/ + function testGetParameters() { + $Docs = new FunctionDocumentor('my_random_test_function'); + $result = $Docs->getParameters(); + $expected = array( + 'param' => array( + 'optional' => false, + 'default' => NULL, + 'position' => 0, + 'type' => 'string', + 'comment' => 'this is a param' + ), + 'one' => array( + 'optional' => true, + 'default' => 'foo', + 'position' => 1, + 'type' => 'string', + 'comment' => 'this is one' + ), + 'two' => array( + 'optional' => true, + 'default' => 'param', + 'position' => 2, + 'type' => 'string', + 'comment' => 'this is two' + ) + ); + $this->assertEqual($result, $expected); + } } \ No newline at end of file diff --git a/tests/cases/vendors/introspector.test.php b/tests/cases/vendors/introspector.test.php index aaf1d6e..fd9cad3 100644 --- a/tests/cases/vendors/introspector.test.php +++ b/tests/cases/vendors/introspector.test.php @@ -39,7 +39,7 @@ class IntrospectorTestCase extends CakeTestCase { EOD; $result = Introspector::parseDocBlock($comment); $expected = array( - 'desc' => "This is the title\n\nThis is my long description", + 'description' => "This is the title\n\nThis is my long description", 'tags' => array ( 'param' => array( 'foo' => array( @@ -70,7 +70,7 @@ EOD; EOD; $result = Introspector::parseDocBlock($comment); $expected = array( - 'desc' => "This is the title\n\nThis is my long description", + 'description' => "This is the title\n\nThis is my long description", 'tags' => array ( 'param' => array( 'foo' => array( diff --git a/vendors/class_documentor.php b/vendors/class_documentor.php index 35b5f42..efefe06 100644 --- a/vendors/class_documentor.php +++ b/vendors/class_documentor.php @@ -10,6 +10,24 @@ App::import('Vendor', 'ApiGenerator.Introspector'); */ class ClassDocumentor extends ReflectionClass { /** + * class Information + * + * @var array + **/ + public $classInfo; +/** + * properties + * + * @var array + **/ + public $properties; +/** + * methods in consumed class + * + * @var array + **/ + public $methods; +/** * getClassInfo * * Get Basic classInfo about the current class diff --git a/vendors/function_documentor.php b/vendors/function_documentor.php index cf7dec3..8f68892 100644 --- a/vendors/function_documentor.php +++ b/vendors/function_documentor.php @@ -29,7 +29,73 @@ App::import('Vendor', 'ApiGenerator.Introspector'); class FunctionDocumentor extends ReflectionFunction { - +/** + * Information about the function + * + * @var array + **/ + public $info; +/** + * Params the function has + * + * @var string + **/ + public $params; +/** + * get General information about the function + * doc block, declared line/file etc. + * + * @return array + **/ + public function getInfo() { + $info = array( + 'name' => $this->getName(), + 'comment' => $this->_parseComment($this->getDocComment()), + 'declaredInFile' => $this->getFileName(), + 'startLine' => $this->getStartLine(), + 'endLine' => $this->getEndLine(), + 'internal' => $this->isInternal() + ); + $this->info = $info; + return $this->info; + } +/** + * Get all the information for each parameter the function has + * + * @return array + **/ + public function getParameters() { + $params = parent::getParameters(); + if (!isset($this->info['comment']['tags']['param'])) { + $this->getInfo(); + } + foreach ($params as $param) { + $type = $description = null; + if (isset($this->info['comment']['tags']['param'][$param->name])) { + extract($this->info['comment']['tags']['param'][$param->name]); + } + $this->params[$param->name] = array( + 'optional' => $param->isOptional(), + 'default' => null, + 'position' => $param->getPosition(), + 'type' => $type, + 'comment' => $description + ); + if ($param->isDefaultValueAvailable()) { + $this->params[$param->name]['default'] = $param->getDefaultValue(); + } + } + return $this->params; + } +/** + * getAll docs for the current function documentor + * + * @return object + **/ + public function getAll() { + $this->getInfo(); + $this->getParameters(); + } /** * _parseComment * diff --git a/vendors/introspector.php b/vendors/introspector.php index 466b76a..3c02e9a 100644 --- a/vendors/introspector.php +++ b/vendors/introspector.php @@ -124,7 +124,7 @@ class Introspector { $tags['param'][$name] = compact('type', 'description'); } } - $com['desc'] = trim($desc); + $com['description'] = trim($desc); $com['tags'] = $tags; return $com; } diff --git a/views/elements/class_info.ctp b/views/elements/class_info.ctp index 85d97cc..ba26a6e 100644 --- a/views/elements/class_info.ctp +++ b/views/elements/class_info.ctp @@ -13,7 +13,7 @@ <dt>File name:</dt> <dd><?php echo $apiDoc->trimFileName($doc->classInfo['fileName']); ?></dd> <dt>Summary:</dt> - <dd class="markdown-block"><?php echo $doc->classInfo['comment']['desc']; ?></dd> + <dd class="markdown-block"><?php echo $doc->classInfo['comment']['description']; ?></dd> </dl> <div class="tag-block"> <dl> diff --git a/views/elements/method_detail.ctp b/views/elements/method_detail.ctp index f370cd7..c404930 100644 --- a/views/elements/method_detail.ctp +++ b/views/elements/method_detail.ctp @@ -18,7 +18,7 @@ </div> <div class="doc-body"> - <div class="markdown-block"><?php echo $method['comment']['desc']; ?></div> + <div class="markdown-block"><?php echo $method['comment']['description']; ?></div> <dl> <?php if (count($method['args'])): ?> <dt>Parameters:</dt> diff --git a/views/elements/method_summary.ctp b/views/elements/method_summary.ctp index 6bc8ab5..8fca8d5 100644 --- a/views/elements/method_summary.ctp +++ b/views/elements/method_summary.ctp @@ -23,7 +23,7 @@ <td><?php echo $html->link($method['name'], '#method-' . $method['name'], array('class' => 'scroll-link')); ?></td> - <td><?php echo $method['comment']['desc']; ?></td> + <td><?php echo $method['comment']['description']; ?></td> </tr> <?php $i++;?> <?php endforeach; ?> diff --git a/views/elements/properties.ctp b/views/elements/properties.ctp index a142286..6bf462e 100644 --- a/views/elements/properties.ctp +++ b/views/elements/properties.ctp @@ -19,7 +19,7 @@ <tr class="<?php echo ($i % 2) ? 'even' : 'odd'; ?> <?php echo $definedInThis ? '' : 'parent-property'; ?>"> <td class="access <?php echo $prop['access']; ?>"><span><?php echo $prop['access']; ?></span></td> <td><?php echo $prop['name']; ?></td> - <td class="markdown-block"><?php echo $prop['comment']['desc']; ?></td> + <td class="markdown-block"><?php echo $prop['comment']['description']; ?></td> </tr> <?php $i++;?> <?php endforeach; ?>