Skip to content

Y
yii2
Commit 3f1a0307 by Carsten Brandt
Options

improved problems reporting in apidoc command

parent e2b34f2c
Showing with 96 additions and 35 deletions
extensions/apidoc/commands/RenderController.php
......@@ -105,6 +105,8 @@ class RenderController extends Controller
// render models
$renderer->renderApi($context, $this);
print_r($context->errors);
// render guide if specified
if ($this->guide !== null) {
$renderer->renderMarkdownFiles($this->findMarkdownFiles($this->guide, ['README.md']), $this);
......
extensions/apidoc/helpers/Markdown.php
......@@ -52,6 +52,10 @@ class Markdown extends \yii\helpers\Markdown
}
$type = static::$renderer->context->getType($typeName);
if ($type === null) {
static::$renderer->context->errors[] = [
'file' => ($context !== null) ? $context->sourceFile : null,
'message' => 'broken link to ' . $typeName . '::' . $subjectName . (($context !== null) ? ' in ' . $context->name : ''),
];
return '<span style="background: #f00;">' . $typeName . '::' . $subjectName . '</span>';
} else {
if (($subject = $type->findSubject($subjectName)) !== null) {
......@@ -63,6 +67,10 @@ class Markdown extends \yii\helpers\Markdown
}
return static::$renderer->subjectLink($subject, $title);
} else {
static::$renderer->context->errors[] = [
'file' => ($context !== null) ? $context->sourceFile : null,
'message' => 'broken link to ' . $type->name . '::' . $subjectName . (($context !== null) ? ' in ' . $context->name : ''),
];
return '<span style="background: #ff0;">' . $type->name . '</span><span style="background: #f00;">::' . $subjectName . '</span>';
}
}
......@@ -76,6 +84,10 @@ class Markdown extends \yii\helpers\Markdown
if (($type = static::$renderer->context->getType($object)) !== null) {
return static::$renderer->typeLink($type, $title);
}
static::$renderer->context->errors[] = [
'file' => ($context !== null) ? $context->sourceFile : null,
'message' => 'broken link to ' . $object . (($context !== null) ? ' in ' . $context->name : ''),
];
return '<span style="background: #f00;">' . $object . '</span>';
}, $content);
......
extensions/apidoc/models/BaseDoc.php
......@@ -10,6 +10,7 @@ namespace yii\apidoc\models;
use phpDocumentor\Reflection\DocBlock\Tag\DeprecatedTag;
use phpDocumentor\Reflection\DocBlock\Tag\SinceTag;
use yii\base\Object;
use yii\helpers\StringHelper;
/**
* Base class for API documentation information.
......@@ -44,9 +45,10 @@ class BaseDoc extends Object
/**
* @param \phpDocumentor\Reflection\BaseReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($config);
......@@ -62,6 +64,13 @@ class BaseDoc extends Object
$docblock = $reflector->getDocBlock();
if ($docblock !== null) {
$this->shortDescription = ucfirst($docblock->getShortDescription());
if (empty($this->shortDescription) && !($this instanceof PropertyDoc) && $context !== null) {
$context->errors[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => "No short description for " . substr(StringHelper::basename(get_class($this)), 0, -3) . " '{$this->name}'",
];
}
$this->description = $docblock->getLongDescription();
$this->phpDocContext = $docblock->getContext();
......@@ -77,6 +86,12 @@ class BaseDoc extends Object
unset($this->tags[$i]);
}
}
} elseif ($context !== null) {
$context->errors[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => "No docblock for element '{$this->name}'",
];
}
}
......
extensions/apidoc/models/ClassDoc.php
......@@ -72,11 +72,12 @@ class ClassDoc extends TypeDoc
/**
* @param \phpDocumentor\Reflection\ClassReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
if ($reflector === null) {
return;
......
extensions/apidoc/models/ConstDoc.php
......@@ -20,11 +20,12 @@ class ConstDoc extends BaseDoc
/**
* @param \phpDocumentor\Reflection\ClassReflector\ConstantReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
if ($reflector === null) {
return;
......
extensions/apidoc/models/Context.php
......@@ -35,6 +35,8 @@ class Context extends Component
*/
public $traits = [];
public $errors = [];
public function getType($type)
{
......@@ -57,18 +59,15 @@ class Context extends Component
$reflection->process();
foreach($reflection->getClasses() as $class) {
$class = new ClassDoc($class);
$class->sourceFile = $fileName;
$class = new ClassDoc($class, $this, ['sourceFile' => $fileName]);
$this->classes[$class->name] = $class;
}
foreach($reflection->getInterfaces() as $interface) {
$interface = new InterfaceDoc($interface);
$interface->sourceFile = $fileName;
$interface = new InterfaceDoc($interface, $this, ['sourceFile' => $fileName]);
$this->interfaces[$interface->name] = $interface;
}
foreach($reflection->getTraits() as $trait) {
$trait = new TraitDoc($trait);
$trait->sourceFile = $fileName;
$trait = new TraitDoc($trait, $this, ['sourceFile' => $fileName]);
$this->traits[$trait->name] = $trait;
}
}
......@@ -160,13 +159,18 @@ class Context extends Component
if (isset($class->properties[$propertyName])) {
$property = $class->properties[$propertyName];
if ($property->getter === null && $property->setter === null) {
echo "Property $propertyName conflicts with a defined getter {$method->name} in {$class->name}.\n"; // TODO log these messages somewhere
$this->errors[] = [
'line' => $property->startLine,
'file' => $class->sourceFile,
'message' => "Property $propertyName conflicts with a defined getter {$method->name} in {$class->name}.",
];
}
$property->getter = $method;
} else {
$class->properties[$propertyName] = new PropertyDoc(null, [
$class->properties[$propertyName] = new PropertyDoc(null, $this, [
'name' => $propertyName,
'definedBy' => $class->name,
'sourceFile' => $class->sourceFile,
'visibility' => 'public',
'isStatic' => false,
'type' => $method->returnType,
......@@ -184,14 +188,19 @@ class Context extends Component
if (isset($class->properties[$propertyName])) {
$property = $class->properties[$propertyName];
if ($property->getter === null && $property->setter === null) {
echo "Property $propertyName conflicts with a defined setter {$method->name} in {$class->name}.\n"; // TODO log these messages somewhere
$this->errors[] = [
'line' => $property->startLine,
'file' => $class->sourceFile,
'message' => "Property $propertyName conflicts with a defined setter {$method->name} in {$class->name}.",
];
}
$property->setter = $method;
} else {
$param = $this->getFirstNotOptionalParameter($method);
$class->properties[$propertyName] = new PropertyDoc(null, [
$class->properties[$propertyName] = new PropertyDoc(null, $this, [
'name' => $propertyName,
'definedBy' => $class->name,
'sourceFile' => $class->sourceFile,
'visibility' => 'public',
'isStatic' => false,
'type' => $param->type,
......
extensions/apidoc/models/EventDoc.php
......@@ -23,11 +23,12 @@ class EventDoc extends ConstDoc
/**
* @param \phpDocumentor\Reflection\ClassReflector\ConstantReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
if ($reflector === null) {
return;
......
extensions/apidoc/models/FunctionDoc.php
......@@ -33,11 +33,12 @@ class FunctionDoc extends BaseDoc
/**
* @param \phpDocumentor\Reflection\FunctionReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
if ($reflector === null) {
return;
......@@ -46,7 +47,7 @@ class FunctionDoc extends BaseDoc
$this->isReturnByReference = $reflector->isByRef();
foreach($reflector->getArguments() as $arg) {
$arg = new ParamDoc($arg);
$arg = new ParamDoc($arg, $context, ['sourceFile' => $this->sourceFile]);
$this->params[$arg->name] = $arg;
}
......@@ -58,8 +59,12 @@ class FunctionDoc extends BaseDoc
// ignore property tag
} elseif ($tag instanceof ParamTag) {
$paramName = $tag->getVariableName();
if (!isset($this->params[$paramName])) {
echo 'undefined parameter documented: ' . $paramName . ' in ' . $this->name . "()\n"; // TODO log these messages somewhere
if (!isset($this->params[$paramName]) && $context !== null) {
$context->errors[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => "Undefined parameter documented: $paramName in {$this->name}().",
];
continue;
}
$this->params[$paramName]->description = ucfirst($tag->getDescription());
......
extensions/apidoc/models/InterfaceDoc.php
......@@ -22,11 +22,12 @@ class InterfaceDoc extends TypeDoc
/**
* @param \phpDocumentor\Reflection\InterfaceReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
if ($reflector === null) {
return;
......
extensions/apidoc/models/MethodDoc.php
......@@ -27,11 +27,12 @@ class MethodDoc extends FunctionDoc
/**
* @param \phpDocumentor\Reflection\ClassReflector\MethodReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
if ($reflector === null) {
return;
......
extensions/apidoc/models/ParamDoc.php
......@@ -28,12 +28,14 @@ class ParamDoc extends Object
public $description;
public $type;
public $types;
public $sourceFile;
/**
* @param \phpDocumentor\Reflection\FunctionReflector\ArgumentReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($config);
......
extensions/apidoc/models/PropertyDoc.php
......@@ -44,11 +44,12 @@ class PropertyDoc extends BaseDoc
/**
* @param \phpDocumentor\Reflection\ClassReflector\PropertyReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
if ($reflector === null) {
return;
......@@ -74,5 +75,12 @@ class PropertyDoc extends BaseDoc
}
}
}
if (empty($this->shortDescription) && $context !== null) {
$context->errors[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => "No short description for element '{$this->name}'",
];
}
}
}
\ No newline at end of file
extensions/apidoc/models/TraitDoc.php
......@@ -23,11 +23,12 @@ class TraitDoc extends TypeDoc
/**
* @param \phpDocumentor\Reflection\TraitReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
if ($reflector === null) {
return;
......
extensions/apidoc/models/TypeDoc.php
......@@ -155,11 +155,12 @@ class TypeDoc extends BaseDoc
/**
* @param \phpDocumentor\Reflection\InterfaceReflector $reflector
* @param Context $context
* @param array $config
*/
public function __construct($reflector = null, $config = [])
public function __construct($reflector = null, $context = null, $config = [])
{
parent::__construct($reflector, $config);
parent::__construct($reflector, $context, $config);
$this->namespace = StringHelper::dirname($this->name);
......@@ -176,7 +177,7 @@ class TypeDoc extends BaseDoc
foreach($reflector->getProperties() as $propertyReflector) {
if ($propertyReflector->getVisibility() != 'private') {
$property = new PropertyDoc($propertyReflector);
$property = new PropertyDoc($propertyReflector, $context, ['sourceFile' => $this->sourceFile]);
$property->definedBy = $this->name;
$this->properties[$property->name] = $property;
}
......@@ -184,7 +185,7 @@ class TypeDoc extends BaseDoc
foreach($reflector->getMethods() as $methodReflector) {
if ($methodReflector->getVisibility() != 'private') {
$method = new MethodDoc($methodReflector);
$method = new MethodDoc($methodReflector, $context, ['sourceFile' => $this->sourceFile]);
$method->definedBy = $this->name;
$this->methods[$method->name] = $method;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment