From 14181b2be0bffac55dd4123bb039e3a1abcabaef Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Wed, 28 Aug 2013 11:36:25 +0200 Subject: [PATCH] Update PHPDoc command to update classfiles automatically --- build/controllers/PhpDocController.php | 172 +++++++++++++++++++++++++++++---- framework/yii/db/redis/Connection.php | 1 + framework/yii/db/redis/Transaction.php | 1 + 3 files changed, 153 insertions(+), 21 deletions(-) diff --git a/build/controllers/PhpDocController.php b/build/controllers/PhpDocController.php index 444d33e..7f1ba58 100644 --- a/build/controllers/PhpDocController.php +++ b/build/controllers/PhpDocController.php @@ -9,6 +9,7 @@ namespace yii\build\controllers; use yii\console\Controller; use yii\helpers\Console; +use yii\helpers\FileHelper; /** * PhpDocController is there to help maintaining PHPDoc annotation in class files @@ -21,40 +22,162 @@ class PhpDocController extends Controller /** * Generates @property annotations in class files from getters and setters * - * @param string $directory the directory to parse files from - * @param boolean $updateFiles whether to update class docs directly + * @param null $root the directory to parse files from + * @param bool $updateFiles whether to update class docs directly */ - public function actionProperty($directory=null, $updateFiles=false) + public function actionProperty($root=null, $updateFiles=true) { - if ($directory === null) { - $directory = dirname(dirname(__DIR__)) . '/framework/yii'; + if ($root === null) { + $root = YII_PATH; } - + $root = FileHelper::normalizePath($root); + $options = array( + 'filter' => function ($path) { + if (is_file($path)) { + $file = basename($path); + if ($file[0] < 'A' || $file[0] > 'Z') { + return false; + } + } + return null; + }, + 'only' => array('.php'), + 'except' => array( + 'YiiBase.php', + 'Yii.php', + '/debug/views/', + '/requirements/', + '/gii/views/', + '/gii/generators/', + ), + ); + $files = FileHelper::findFiles($root, $options); $nFilesTotal = 0; - $files = new \RegexIterator( - new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($directory)), - '#^.+\.php$#i', - \RecursiveRegexIterator::GET_MATCH - ); + $nFilesUpdated = 0; foreach ($files as $file) { - list($className, $phpdoc) = $this->generateClassPropertyDocs($file[0]); - if ($phpdoc !== false) { + $result = $this->generateClassPropertyDocs($file); + if ($result !== false) { + list($className, $phpdoc) = $result; if ($updateFiles) { - $this->updateClassPropertyDocs($file[0], $className, $phpdoc); - } else { - $this->stdout("\n[ " . $file[0] . " ]\n\n", Console::BOLD); - $this->stdout($phpdoc . "\n"); + if ($this->updateClassPropertyDocs($file, $className, $phpdoc)) { + $nFilesUpdated++; + } + } elseif (!empty($phpdoc)) { + $this->stdout("\n[ " . $file . " ]\n\n", Console::BOLD); + $this->stdout($phpdoc); } } $nFilesTotal++; } $this->stdout("\n\nParsed $nFilesTotal files.\n"); + $this->stdout("Updated $nFilesUpdated files.\n"); } - protected function updateClassPropertyDocs($file, $className, $phpDoc) + protected function updateClassPropertyDocs($file, $className, $propertyDoc) { - // TODO implement + $ref = new \ReflectionClass($className); + if ($ref->getFileName() != $file) { + $this->stderr("[ERR] Unable to create ReflectionClass for class: $className loaded class is not from file: $file\n", Console::FG_RED); + } + + $oldDoc = $ref->getDocComment(); + $newDoc = $this->cleanDocComment($this->updateDocComment($oldDoc, $propertyDoc)); + + $seenSince = false; + $seenAuthor = false; + + $lines = explode("\n", $newDoc); + foreach($lines as $line) { + if (substr(trim($line), 0, 9) == '* @since ') { + $seenSince = true; + } elseif (substr(trim($line), 0, 10) == '* @author ') { + $seenAuthor = true; + } + } + + if (!$seenSince) { + $this->stderr("[ERR] No @since found in class doc in file: $file\n", Console::FG_RED); + } + if (!$seenAuthor) { + $this->stderr("[ERR] No @author found in class doc in file: $file\n", Console::FG_RED); + } + + if ($oldDoc != $newDoc) { + + $fileContent = file($file); + $start = $ref->getStartLine(); + $docStart = $start - count(explode("\n", $oldDoc)); + + $newFileContent = array(); + foreach($fileContent as $i => $line) { + if ($i > $start || $i < $docStart) { + $newFileContent[] = $line; + } else { + $newFileContent[] = trim($newDoc); + } + } + + file_put_contents($file, implode("\n", $newFileContent)); + + return true; + } + return false; + } + + /** + * remove multi empty lines and trim trailing whitespace + * + * @param $doc + * @return string + */ + protected function cleanDocComment($doc) + { + $lines = explode("\n", $doc); + $n = count($lines); + for($i = 0; $i < $n; $i++) { + $lines[$i] = rtrim($lines[$i]); + if (trim($lines[$i]) == '*' && trim($lines[$i + 1]) == '*') { + unset($lines[$i]); + } + } + return implode("\n", $lines); + } + + /** + * replace property annotations in doc comment + * @param $doc + * @param $properties + * @return string + */ + protected function updateDocComment($doc, $properties) + { + $lines = explode("\n", $doc); + $propertyPart = false; + $propertyPosition = false; + foreach($lines as $i => $line) { + if (substr(trim($line), 0, 12) == '* @property ') { + $propertyPart = true; + } elseif ($propertyPart && trim($line) == '*') { + $propertyPosition = $i; + $propertyPart = false; + } + if (substr(trim($line), 0, 10) == '* @author ' && $propertyPosition === false) { + $propertyPosition = $i; + $propertyPart = false; + } + if ($propertyPart) { + unset($lines[$i]); + } + } + $finalDoc = ''; + foreach($lines as $i => $line) { + $finalDoc .= $line . "\n"; + if ($i == $propertyPosition) { + $finalDoc .= $properties; + } + } + return $finalDoc; } protected function generateClassPropertyDocs($fileName) @@ -64,14 +187,21 @@ class PhpDocController extends Controller $ns = $this->match('#\nnamespace (?[\w\\\\]+);\n#', $file); $namespace = reset($ns); $namespace = $namespace['name']; - $classes = $this->match('#\n(?:abstract )?class (?\w+) extends .+\{(?.+)\n\}(\n|$)#', $file); + $classes = $this->match('#\n(?:abstract )?class (?\w+)( |\n)(extends )?.+\{(?.*)\n\}(\n|$)#', $file); if (count($classes) > 1) { $this->stderr("[ERR] There should be only one class in a file: $fileName\n", Console::FG_RED); return false; } if (count($classes) < 1) { - $this->stderr("[ERR] No class in file: $fileName\n", Console::FG_RED); + $interfaces = $this->match('#\ninterface (?\w+)\n\{(?.+)\n\}(\n|$)#', $file); + if (count($interfaces) == 1) { + return false; + } elseif (count($interfaces) > 1) { + $this->stderr("[ERR] There should be only one interface in a file: $fileName\n", Console::FG_RED); + } else { + $this->stderr("[ERR] No class in file: $fileName\n", Console::FG_RED); + } return false; } diff --git a/framework/yii/db/redis/Connection.php b/framework/yii/db/redis/Connection.php index 46db575..4a297d7 100644 --- a/framework/yii/db/redis/Connection.php +++ b/framework/yii/db/redis/Connection.php @@ -23,6 +23,7 @@ use yii\helpers\StringHelper; * @method mixed get($key) Set the string value of a key * TODO document methods * + * @author Carsten Brandt * @since 2.0 */ class Connection extends Component diff --git a/framework/yii/db/redis/Transaction.php b/framework/yii/db/redis/Transaction.php index 721a7be..97c5c88 100644 --- a/framework/yii/db/redis/Transaction.php +++ b/framework/yii/db/redis/Transaction.php @@ -17,6 +17,7 @@ use yii\db\Exception; * * @property boolean $isActive Whether the transaction is active. This property is read-only. * + * @author Carsten Brandt * @since 2.0 */ class Transaction extends \yii\base\Object