apidoc minor fixes: phpdoc, use statements, comments

extensions/apidoc/components/BaseController.php

@@ -31,6 +31,11 @@ abstract class BaseController extends Controller
     public $exclude;
 
 
+    /**
+     * Checks that target directory is valid. Asks questions in tricky cases.
+     * @param string $target
+     * @return boolean|string
+     */
     protected function normalizeTargetDir($target)
     {
         $target = rtrim(Yii::getAlias($target), '\\/');
@@ -52,6 +57,11 @@ abstract class BaseController extends Controller
         return $target;
     }
 
+    /**
+     * Finds files to process
+     * @param array $sourceDirs
+     * @return array|boolean list of files to process or false on failure
+     */
     protected function searchFiles($sourceDirs)
     {
         $this->stdout('Searching files to process... ');
@@ -81,8 +91,20 @@ abstract class BaseController extends Controller
         return $files;
     }
 
+    /**
+     * Finds files
+     *
+     * @param string $dir directory to search files in.
+     * @param array $except list of names to exclude from search.
+     * @return array files found.
+     */
     abstract protected function findFiles($dir, $except = []);
 
+    /**
+     * Loads context from cache
+     * @param string $location
+     * @return Context
+     */
     protected function loadContext($location)
     {
         $context = new Context();
@@ -99,6 +121,11 @@ abstract class BaseController extends Controller
         return $context;
     }
 
+    /**
+     * Writes context into cache file
+     * @param Context $context
+     * @param string $location
+     */
     protected function storeContext($context, $location)
     {
         $cacheFile = $location . '/cache/apidoc.data';

extensions/apidoc/helpers/ApiIndexer.php

@@ -11,8 +11,18 @@ use cebe\jssearch\Indexer;
 use cebe\jssearch\tokenizer\StandardTokenizer;
 use cebe\jssearch\TokenizerInterface;
 
+/**
+ * ApiIndexer indexes framework API
+ */
 class ApiIndexer extends Indexer
 {
+    /**
+     * @param string $file
+     * @param string $contents
+     * @param string $basePath
+     * @param string $baseUrl
+     * @return array
+     */
     protected function generateFileInfo($file, $contents, $basePath, $baseUrl)
     {
         // create file entry

extensions/apidoc/helpers/ApiMarkdown.php

@@ -33,7 +33,7 @@ class ApiMarkdown extends GithubMarkdown
 
 
     /**
-     * Renders a code block
+     * @inheritdoc
      */
     protected function renderCode($block)
     {
@@ -46,6 +46,13 @@ class ApiMarkdown extends GithubMarkdown
         }
     }
 
+    /**
+     * Highlights code
+     *
+     * @param string $code code to highlight
+     * @param string $language language of the code to highlight
+     * @return string HTML of highlighted code
+     */
     public static function highlight($code, $language)
     {
         if ($language !== 'php') {

extensions/apidoc/helpers/ApiMarkdownLaTeX.php

@@ -30,6 +30,9 @@ class ApiMarkdownLaTeX extends GithubMarkdown
     protected $renderingContext;
 
 
+    /**
+     * @inheritdoc
+     */
     protected function renderApiLink($block)
     {
         // TODO allow break also on camel case
@@ -37,6 +40,9 @@ class ApiMarkdownLaTeX extends GithubMarkdown
         return $latex;
     }
 
+    /**
+     * @inheritdoc
+     */
     protected function renderBrokenApiLink($block)
     {
         return $this->renderApiLink($block);

extensions/apidoc/helpers/ApiMarkdownTrait.php

@@ -112,11 +112,21 @@ trait ApiMarkdownTrait
         return [['text', '[['], 2];
     }
 
+    /**
+     * Renders API link
+     * @param array $block
+     * @return string
+     */
     protected function renderApiLink($block)
     {
         return $block[1];
     }
 
+    /**
+     * Renders API link that is broken i.e. points nowhere
+     * @param array $block
+     * @return string
+     */
     protected function renderBrokenApiLink($block)
     {
         return $block[1];

extensions/apidoc/helpers/IndexFileAnalyzer.php

@@ -9,6 +9,9 @@ namespace yii\apidoc\helpers;
 
 use cebe\markdown\Markdown;
 
+/**
+ * IndexFileAnalyzer analyzes index file with TOC. Typically README.md.
+ */
 class IndexFileAnalyzer extends Markdown
 {
     public $title;
@@ -18,6 +21,11 @@ class IndexFileAnalyzer extends Markdown
     private $_chapters = [];
 
 
+    /**
+     * Parses text and returns list of chapters got from it
+     * @param string $text
+     * @return array
+     */
     public function analyze($text)
     {
         $this->parse($text);
@@ -25,6 +33,9 @@ class IndexFileAnalyzer extends Markdown
         return $this->_chapters;
     }
 
+    /**
+     * @inheritdoc
+     */
     protected function renderHeadline($block)
     {
         if ($this->_chapter === 0) {
@@ -41,6 +52,9 @@ class IndexFileAnalyzer extends Markdown
         return parent::renderHeadline($block);
     }
 
+    /**
+     * @inheritdoc
+     */
     protected function renderParagraph($block)
     {
         if ($this->_chapter < 1) {
@@ -49,6 +63,9 @@ class IndexFileAnalyzer extends Markdown
         return parent::renderParagraph($block);
     }
 
+    /**
+     * @inheritdoc
+     */
     protected function renderList($block)
     {
         if ($this->_chapter > 0) {

extensions/apidoc/helpers/PrettyPrinter.php

@@ -18,6 +18,10 @@ use PHPParser_Node_Expr_Array;
  */
 class PrettyPrinter extends \phpDocumentor\Reflection\PrettyPrinter
 {
+    /**
+     * @param PHPParser_Node_Expr_Array $node
+     * @return string
+     */
     public function pExpr_Array(PHPParser_Node_Expr_Array $node)
     {
         return '[' . $this->pCommaSeparated($node->items) . ']';

extensions/apidoc/models/BaseDoc.php

@@ -39,6 +39,11 @@ class BaseDoc extends Object
     public $tags = [];
 
 
+    /**
+     * Checks if doc has tag of a given name
+     * @param string $name tag name
+     * @return boolean if doc has tag of a given name
+     */
     public function hasTag($name)
     {
         foreach ($this->tags as $tag) {
@@ -49,6 +54,10 @@ class BaseDoc extends Object
         return false;
     }
 
+    /**
+     * Removes tag of a given name
+     * @param string $name
+     */
     public function removeTag($name)
     {
         foreach ($this->tags as $i => $tag) {
@@ -125,6 +134,11 @@ class BaseDoc extends Object
 //		return implode("", array_slice($lines, $this->startLine - 1, $this->endLine - $this->startLine + 1));
 //	}
 
+    /**
+     * Extracts first sentence out of text
+     * @param string $text
+     * @return string
+     */
     public static function extractFirstSentence($text)
     {
         if (mb_strlen($text) > 4 && ($pos = mb_strpos($text, '.', 4, 'utf-8')) !== false) {

extensions/apidoc/models/ClassDoc.php

@@ -37,6 +37,9 @@ class ClassDoc extends TypeDoc
     public $constants = [];
 
 
+    /**
+     * @inheritdoc
+     */
     public function findSubject($subjectName)
     {
         if (($subject = parent::findSubject($subjectName)) !== null) {
@@ -73,9 +76,7 @@ class ClassDoc extends TypeDoc
     }
 
     /**
-     * @param \phpDocumentor\Reflection\ClassReflector $reflector
-     * @param Context $context
-     * @param array $config
+     * @inheritdoc
      */
     public function __construct($reflector = null, $context = null, $config = [])
     {

extensions/apidoc/models/Context.php

@@ -36,6 +36,11 @@ class Context extends Component
     public $errors = [];
 
 
+    /**
+     * Returning TypeDoc for a type given
+     * @param string $type
+     * @return null|ClassDoc|InterfaceDoc|TraitDoc
+     */
     public function getType($type)
     {
         $type = ltrim($type, '\\');
@@ -50,6 +55,10 @@ class Context extends Component
         return null;
     }
 
+    /**
+     * Adds file to context
+     * @param string $fileName
+     */
     public function addFile($fileName)
     {
         $this->files[$fileName] = sha1_file($fileName);
@@ -71,6 +80,9 @@ class Context extends Component
         }
     }
 
+    /**
+     * Updates references
+     */
     public function updateReferences()
     {
         // update all subclass references
@@ -208,7 +220,8 @@ class Context extends Component
 
     /**
      * @param MethodDoc $method
-     * @param ClassDoc $parent
+     * @param ClassDoc $class
+     * @return mixed
      */
     private function inheritMethodRecursive($method, $class)
     {

extensions/apidoc/models/PropertyDoc.php

@@ -30,11 +30,17 @@ class PropertyDoc extends BaseDoc
     public $definedBy;
 
 
+    /**
+     * @return bool if property is read only
+     */
     public function getIsReadOnly()
     {
         return $this->getter !== null && $this->setter === null;
     }
 
+    /**
+     * @return bool if property is write only
+     */
     public function getIsWriteOnly()
     {
         return $this->getter === null && $this->setter !== null;

extensions/apidoc/renderers/BaseRenderer.php

@@ -158,6 +158,7 @@ abstract class BaseRenderer extends Component
 
     /**
      * @param BaseDoc $context
+     * @return string
      */
     private function resolveNamespace($context)
     {

extensions/apidoc/renderers/GuideRenderer.php

@@ -27,6 +27,11 @@ abstract class GuideRenderer extends BaseRenderer
     abstract public function render($files, $targetDir);
 
 
+    /**
+     * Loads guide structure from a set of files
+     * @param array $files
+     * @return array
+     */
     protected function loadGuideStructure($files)
     {
         $chapters = [];

extensions/apidoc/templates/bootstrap/ApiRenderer.php

@@ -92,6 +92,9 @@ class ApiRenderer extends \yii\apidoc\templates\html\ApiRenderer
         }
     }
 
+    /**
+     * @inheritdoc
+     */
     public function getSourceUrl($type, $line = null)
     {
         if (is_string($type)) {

extensions/apidoc/templates/bootstrap/RendererTrait.php

@@ -7,8 +7,16 @@
 
 namespace yii\apidoc\templates\bootstrap;
 
+use yii\apidoc\models\TypeDoc;
+
+/**
+ * Common methods for renderers
+ */
 trait RendererTrait
 {
+    /**
+     * @var array official Yii extensions
+     */
     public $extensions = [
         'apidoc',
         'authclient',
@@ -29,6 +37,12 @@ trait RendererTrait
         'twig',
     ];
 
+    /**
+     * Returns nav TypeDocs
+     * @param TypeDoc $type typedoc to take category from
+     * @param TypeDoc[] $types TypeDocs to filter
+     * @return array
+     */
     public function getNavTypes($type, $types)
     {
         if ($type === null) {
@@ -38,6 +52,11 @@ trait RendererTrait
         return $this->filterTypes($types, $this->getTypeCategory($type));
     }
 
+    /**
+     * Returns category of TypeDoc
+     * @param TypeDoc $type
+     * @return string
+     */
     protected function getTypeCategory($type)
     {
         $extensions = $this->extensions;
@@ -60,6 +79,13 @@ trait RendererTrait
         return $navClasses;
     }
 
+    /**
+     * Returns types of a given class
+     *
+     * @param TypeDoc[] $types
+     * @param string $navClasses
+     * @return array
+     */
     protected function filterTypes($types, $navClasses)
     {
         switch ($navClasses) {

extensions/apidoc/templates/bootstrap/SideNavWidget.php

@@ -10,6 +10,7 @@ namespace yii\apidoc\templates\bootstrap;
 use Yii;
 use yii\base\InvalidConfigException;
 use yii\bootstrap\BootstrapAsset;
+use yii\bootstrap\Widget;
 use yii\helpers\ArrayHelper;
 use yii\helpers\Url;
 use yii\helpers\Html;
@@ -48,7 +49,7 @@ use yii\helpers\Html;
  * @author Antonio Ramirez <amigo.cobos@gmail.com>
  * @since 2.0
  */
-class SideNavWidget extends \yii\bootstrap\Widget
+class SideNavWidget extends Widget
 {
     /**
      * @var array list of items in the nav widget. Each array element represents a single
@@ -134,7 +135,6 @@ class SideNavWidget extends \yii\bootstrap\Widget
         }
 
         $label = $this->encodeLabels ? Html::encode($item['label']) : $item['label'];
-//		$options = ArrayHelper::getValue($item, 'options', []);
         $items = ArrayHelper::getValue($item, 'items');
         $url = Url::to(ArrayHelper::getValue($item, 'url', '#'));
         $linkOptions = ArrayHelper::getValue($item, 'linkOptions', []);

extensions/apidoc/templates/bootstrap/assets/JsSearchAsset.php

@@ -7,6 +7,7 @@
 
 namespace yii\apidoc\templates\bootstrap\assets;
 
+use yii\web\AssetBundle;
 use yii\web\View;
 
 /**
@@ -15,7 +16,7 @@ use yii\web\View;
  * @author Carsten Brandt <mail@cebe.cc>
  * @since 2.0
  */
-class JsSearchAsset extends \yii\web\AssetBundle
+class JsSearchAsset extends AssetBundle
 {
     public $sourcePath = '@vendor/cebe/js-search';
     public $js = [

extensions/apidoc/templates/bootstrap/layouts/main.php

 <?php
 
-use yii\apidoc\renderers\BaseRenderer;
 use yii\bootstrap\Nav;
 use yii\bootstrap\NavBar;
 use yii\helpers\Html;

extensions/apidoc/templates/html/ApiRenderer.php

@@ -127,6 +127,12 @@ class ApiRenderer extends BaseApiRenderer implements ViewContextInterface
         }
     }
 
+    /**
+     * Renders file applying layout
+     * @param string $viewFile the view name
+     * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file.
+     * @return string
+     */
     protected function renderWithLayout($viewFile, $params)
     {
         $output = $this->getView()->render($viewFile, $params, $this);
@@ -259,11 +265,19 @@ class ApiRenderer extends BaseApiRenderer implements ViewContextInterface
             . ApiMarkdown::highlight(str_replace('  ', ' ', '( ' . implode(', ', $params) . ' )'), 'php');
     }
 
+    /**
+     * @inheritdoc
+     */
     public function generateApiUrl($typeName)
     {
         return $this->generateFileName($typeName);
     }
 
+    /**
+     * Generates file name for API page for a given type
+     * @param string $typeName
+     * @return string
+     */
     protected function generateFileName($typeName)
     {
         return strtolower(str_replace('\\', '-', $typeName)) . '.html';
@@ -287,7 +301,10 @@ class ApiRenderer extends BaseApiRenderer implements ViewContextInterface
         return Html::a($text, null, $options);
     }
 
-    public function getSourceUrl($type)
+    /**
+     * @inheritdoc
+     */
+    public function getSourceUrl($type, $line = null)
     {
         return null;
     }

extensions/apidoc/templates/html/GuideRenderer.php

@@ -35,6 +35,9 @@ abstract class GuideRenderer extends BaseGuideRenderer
     private $_targetDir;
 
 
+    /**
+     * @inheritdoc
+     */
     public function init()
     {
         parent::init();
@@ -65,9 +68,10 @@ abstract class GuideRenderer extends BaseGuideRenderer
     }
 
     /**
-     * Renders a given [[Context]].
+     * Renders a set of files given into target directory.
      *
-     * @param Controller $controller the apidoc controller instance. Can be used to control output.
+     * @param array $files
+     * @param string $targetDir
      */
     public function render($files, $targetDir)
     {
@@ -112,6 +116,11 @@ abstract class GuideRenderer extends BaseGuideRenderer
         }
     }
 
+    /**
+     * Given markdown file name generates resulting html file name
+     * @param string $file markdown file name
+     * @return string
+     */
     protected function generateGuideFileName($file)
     {
         return $this->guidePrefix . basename($file, '.md') . '.html';
@@ -128,6 +137,11 @@ abstract class GuideRenderer extends BaseGuideRenderer
 //		return $refs;
     }
 
+    /**
+     * Adds guide name to link URLs in markdown
+     * @param string $content
+     * @return string
+     */
     protected function fixMarkdownLinks($content)
     {
         $content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="' . $this->guidePrefix . '\1.html\2"', $content);
@@ -146,9 +160,7 @@ abstract class GuideRenderer extends BaseGuideRenderer
     }
 
     /**
-     * Generate an url to a type in apidocs
-     * @param $typeName
-     * @return mixed
+     * @inheritdoc
      */
     public function generateApiUrl($typeName)
     {

extensions/apidoc/templates/online/ApiRenderer.php

@@ -54,11 +54,17 @@ class ApiRenderer extends \yii\apidoc\templates\html\ApiRenderer
         }
     }
 
+    /**
+     * @inheritdoc
+     */
     public function generateApiUrl($typeName)
     {
         return strtolower(str_replace('\\', '-', $typeName));
     }
 
+    /**
+     * @inheritdoc
+     */
     protected function generateFileName($typeName)
     {
         return $this->generateApiUrl($typeName) . '.html';