Class yii\apidoc\models\BaseDoc
| Inheritance | yii\apidoc\models\BaseDoc » yii\base\BaseObject |
|---|---|
| Subclasses | yii\apidoc\models\ClassDoc, yii\apidoc\models\ConstDoc, yii\apidoc\models\EventDoc, yii\apidoc\models\FunctionDoc, yii\apidoc\models\InterfaceDoc, yii\apidoc\models\MethodDoc, yii\apidoc\models\PropertyDoc, yii\apidoc\models\TraitDoc, yii\apidoc\models\TypeDoc |
| Available since extension's version | 2.0 |
| Source Code | https://github.com/yiisoft/yii2-apidoc/blob/master/models/BaseDoc.php |
Base class for API documentation information.
Public Properties
Public Methods
| Method | Description | Defined By |
|---|---|---|
| __construct() | yii\apidoc\models\BaseDoc | |
| getFirstTag() | Get the first tag of a given name | yii\apidoc\models\BaseDoc |
| getPackageName() | Returns the Composer package for this type, if it can be determined from $sourceFile. | yii\apidoc\models\BaseDoc |
| hasTag() | Checks if doc has tag of a given name | yii\apidoc\models\BaseDoc |
| removeTag() | Removes tag of a given name | yii\apidoc\models\BaseDoc |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| isInheritdocTag() | yii\apidoc\models\BaseDoc |
Constants
| Constant | Value | Description | Defined By |
|---|---|---|---|
| INHERITDOC_TAG_NAME | 'inheritdoc' | yii\apidoc\models\BaseDoc | |
| PHPSTAN_IMPORT_TYPE_ANNOTATION_NAME | 'phpstan-import-type' | yii\apidoc\models\BaseDoc | |
| PHPSTAN_TYPE_ANNOTATION_NAME | 'phpstan-type' | yii\apidoc\models\BaseDoc | |
| PSALM_IMPORT_TYPE_ANNOTATION_NAME | 'psalm-import-type' | yii\apidoc\models\BaseDoc | |
| PSALM_TYPE_ANNOTATION_NAME | 'psalm-type' | yii\apidoc\models\BaseDoc | |
| TODO_TAG_NAME | 'todo' | yii\apidoc\models\BaseDoc |
Property Details
A mapping where keys are versions and values are descriptions.
Method Details
| public mixed __construct ( self|null $parent = null, \phpDocumentor\Reflection\Php\Class_|\phpDocumentor\Reflection\Php\Method|\phpDocumentor\Reflection\Php\Trait_|\phpDocumentor\Reflection\Php\Interface_|\phpDocumentor\Reflection\Php\Property|\phpDocumentor\Reflection\Php\Constant|null $reflector = null, yii\apidoc\models\Context|null $context = null, array $config = [] ) | ||
| $parent | self|null | |
| $reflector | \phpDocumentor\Reflection\Php\Class_|\phpDocumentor\Reflection\Php\Method|\phpDocumentor\Reflection\Php\Trait_|\phpDocumentor\Reflection\Php\Interface_|\phpDocumentor\Reflection\Php\Property|\phpDocumentor\Reflection\Php\Constant|null | |
| $context | yii\apidoc\models\Context|null | |
| $config | array | |
public function __construct(public $parent = null, $reflector = null, $context = null, $config = [])
{
parent::__construct($config);
if ($reflector === null) {
return;
}
$fqsenResolver = new FqsenResolver();
$typeResolver = new TypeResolver($fqsenResolver);
// base properties
$this->fullName = trim((string) $reflector->getFqsen(), '\\()');
$position = strrpos($this->fullName, '::');
$this->name = $position === false ? $this->fullName : substr($this->fullName, $position + 2);
$this->startLine = $reflector->getLocation()->getLineNumber();
$this->endLine = $reflector->getEndLocation()->getLineNumber();
$docBlock = $reflector->getDocBlock();
if ($docBlock === null) {
if ($context !== null) {
$context->warnings[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => "No docblock for element '{$this->name}'",
];
}
return;
}
$this->shortDescription = StringHelper::mb_ucfirst($docBlock->getSummary());
if (empty($this->shortDescription) && !($this instanceof PropertyDoc) && $context !== null && !$docBlock->getTagsByName(self::INHERITDOC_TAG_NAME)) {
$context->warnings[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => 'No short description for ' . substr(StringHelper::basename(static::class), 0, -3) . " '{$this->name}'",
];
}
$this->description = $docBlock->getDescription()->render();
$this->phpDocContext = $docBlock->getContext();
$this->tags = $docBlock->getTags();
foreach ($this->tags as $i => $tag) {
if ($tag instanceof Since) {
$description = (string) $tag->getDescription();
if (!$this->since && !$this->sinceMap && !$description) {
$this->since = $tag->getVersion();
}
if ($description) {
$this->sinceMap[$tag->getVersion()] = $description;
}
unset($this->tags[$i]);
} elseif ($tag instanceof Deprecated) {
$this->deprecatedSince = $tag->getVersion();
$this->deprecatedReason = (string) $tag->getDescription();
unset($this->tags[$i]);
} elseif ($tag instanceof Template) {
$this->templates[$tag->getTemplateName()] = $tag;
unset($this->tags[$i]);
} elseif ($tag instanceof Generic) {
try {
if ($tag->getName() === self::TODO_TAG_NAME) {
$this->todos[] = $tag;
unset($this->tags[$i]);
} elseif ($tag->getName() === self::PHPSTAN_TYPE_ANNOTATION_NAME) {
$tagData = $this->parsePseudoTypeTag($tag);
$phpStanType = new PseudoTypeDoc(
PseudoTypeDoc::TYPE_PHPSTAN,
$this,
trim($tagData[0]),
$typeResolver->resolve(trim($tagData[1]), $this->phpDocContext),
);
$this->phpStanTypes[$phpStanType->name] = $phpStanType;
unset($this->tags[$i]);
} elseif ($tag->getName() === self::PSALM_TYPE_ANNOTATION_NAME) {
$tagData = $this->parsePseudoTypeTag($tag);
$psalmType = new PseudoTypeDoc(
PseudoTypeDoc::TYPE_PSALM,
$this,
trim($tagData[0]),
$typeResolver->resolve(trim($tagData[1]), $this->phpDocContext),
);
$this->psalmTypes[$psalmType->name] = $psalmType;
unset($this->tags[$i]);
} elseif ($tag->getName() === self::PHPSTAN_IMPORT_TYPE_ANNOTATION_NAME) {
$tagData = $this->parsePseudoTypeImportTag($tag);
$phpStanTypeImport = new PseudoTypeImportDoc(
PseudoTypeImportDoc::TYPE_PHPSTAN,
trim($tagData[0]),
$fqsenResolver->resolve(trim($tagData[1]), $this->phpDocContext),
);
$this->phpStanTypeImports[$phpStanTypeImport->typeName] = $phpStanTypeImport;
unset($this->tags[$i]);
} elseif ($tag->getName() === self::PSALM_IMPORT_TYPE_ANNOTATION_NAME) {
$tagData = $this->parsePseudoTypeImportTag($tag);
$psalmTypeImport = new PseudoTypeImportDoc(
PseudoTypeImportDoc::TYPE_PSALM,
trim($tagData[0]),
$fqsenResolver->resolve(trim($tagData[1]), $this->phpDocContext),
);
$this->psalmTypeImports[$psalmTypeImport->typeName] = $psalmTypeImport;
unset($this->tags[$i]);
}
} catch (InvalidArgumentException | RuntimeException $e) {
if ($context !== null) {
$context->errors[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => 'Exception: ' . $e->getMessage(),
];
} else {
throw $e;
}
}
} elseif ($tag instanceof InvalidTag && $context !== null) {
$exception = $tag->getException();
$message = 'Invalid tag: ' . $tag->render() . '.';
if ($exception !== null) {
$message .= ' Exception message: ' . $exception->getMessage();
}
$context->errors[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => $message,
];
}
}
if (in_array($this->shortDescription, ['{@inheritdoc}', '{@inheritDoc}', '@inheritdoc', '@inheritDoc'], true)) {
// Mock up parsing of '{@inheritdoc}' (in brackets) tag, which is not yet supported at "phpdocumentor/reflection-docblock" 2.x
// todo consider removal in case of "phpdocumentor/reflection-docblock" upgrade
$this->tags[] = new Generic(self::INHERITDOC_TAG_NAME);
$this->shortDescription = '';
}
}
Get the first tag of a given name
| public \phpDocumentor\Reflection\DocBlock\Tag|null getFirstTag ( string $name ) | ||
| $name | string |
Tag name. |
| return | \phpDocumentor\Reflection\DocBlock\Tag|null |
Tag instance, |
|---|---|---|
public function getFirstTag($name)
{
foreach ($this->tags as $i => $tag) {
if (strtolower($tag->getName()) == $name) {
return $this->tags[$i];
}
}
return null;
}
Returns the Composer package for this type, if it can be determined from $sourceFile.
| public string|null getPackageName ( ) |
public function getPackageName()
{
if (!$this->sourceFile || !preg_match('/\/vendor\/([\w\-]+\/[\w\-]+)/', $this->sourceFile, $match)) {
return null;
}
return $match[1];
}
Checks if doc has tag of a given name
| public boolean hasTag ( string $name ) | ||
| $name | string |
Tag name |
| return | boolean |
If doc has tag of a given name |
|---|---|---|
public function hasTag($name)
{
foreach ($this->tags as $tag) {
if (strtolower($tag->getName()) == $name) {
return true;
}
}
return false;
}
| protected boolean isInheritdocTag ( \phpDocumentor\Reflection\DocBlock\Tag $tag ) | ||
| $tag | \phpDocumentor\Reflection\DocBlock\Tag | |
protected function isInheritdocTag(Tag $tag): bool
{
return $tag instanceof Generic && $tag->getName() === self::INHERITDOC_TAG_NAME;
}