Skip to content

Determining types by type hints for properties, methods and params #319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+369 −5
Open

Determining types by type hints for properties, methods and params #319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a15d5b
Determining types by type hints for properties, methods and params
mspirkov Nov 11, 2025
879d76a
self review
mspirkov Nov 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Yii Framework 2 apidoc extension Change Log
- Bug #313: Fix deprecation error `Method deprecated, use ::getParameters()` (mspirkov)
- Bug #317: Fix `trim` deprecation errors `Passing null to parameter #1 ($string) of type string is deprecated` (mspirkov)
- Bug #318: Fix deprecation errors `mb_convert_encoding(): Handling HTML entities via mbstring is deprecated` (mspirkov)
- Enh #319: Determining types by type hints for properties, methods and params (mspirkov)


3.0.7 February 13, 2025
Expand Down
9 changes: 8 additions & 1 deletion models/BaseDoc.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@
*/
class BaseDoc extends BaseObject
{
private const INHERITDOC_TAG_NAME = 'inheritdoc';

/**
* @var \phpDocumentor\Reflection\Types\Context
*/
Expand Down Expand Up @@ -210,11 +212,16 @@ public function __construct($reflector = null, $context = null, $config = [])
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('inheritdoc');
$this->tags[] = new Generic(self::INHERITDOC_TAG_NAME);
$this->shortDescription = '';
}
}

protected function isInheritdocTag(Tag $tag): bool
{
return $tag instanceof Generic && $tag->getName() === self::INHERITDOC_TAG_NAME;
}

/**
* Converts inline links to unified format.
* @see ApiMarkdownTrait::parseApiLinks()
Expand Down
16 changes: 16 additions & 0 deletions models/FunctionDoc.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@

namespace yii\apidoc\models;

use phpDocumentor\Reflection\DocBlock\Tags\Generic;
use phpDocumentor\Reflection\DocBlock\Tags\Param;
use phpDocumentor\Reflection\DocBlock\Tags\Return_;
use phpDocumentor\Reflection\DocBlock\Tags\Throws;
Expand All @@ -27,7 +28,13 @@ class FunctionDoc extends BaseDoc
public $params = [];
public $exceptions = [];
public $return;
/**
* @var string|null
*/
public $returnType;
/**
* @var string[]|null
*/
public $returnTypes;
public $isReturnByReference;

Expand All @@ -52,6 +59,8 @@ public function __construct($reflector = null, $context = null, $config = [])
$this->params[$arg->name] = $arg;
}

$hasInheritdoc = false;

foreach ($this->tags as $i => $tag) {
if ($tag instanceof Throws) {
$this->exceptions[implode($this->splitTypes($tag->getType()))] = $tag->getDescription();
Expand All @@ -75,7 +84,14 @@ public function __construct($reflector = null, $context = null, $config = [])
$this->returnTypes = $this->splitTypes($tag->getType());
$this->return = StringHelper::mb_ucfirst($tag->getDescription());
unset($this->tags[$i]);
} elseif ($this->isInheritdocTag($tag)) {
$hasInheritdoc = true;
}
}

if (!$hasInheritdoc && $this->returnType === null) {
$this->returnType = (string) $reflector->getReturnType();
$this->returnTypes = [$this->returnType];
}
}
}
8 changes: 8 additions & 0 deletions models/ParamDoc.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,13 @@ class ParamDoc extends BaseObject
public $isPassedByReference;
// will be set by creating class
public $description;
/**
* @var string|null
*/
public $type;
/**
* @var string[]|null
*/
public $types;
public $sourceFile;

Expand All @@ -42,6 +48,8 @@ public function __construct($reflector = null, $context = null, $config = [])
if ($reflector !== null) {
$this->name = $reflector->getName();
$this->typeHint = (string) $reflector->getType();
$this->type = $this->typeHint;
$this->types = [$this->type];
$this->defaultValue = $reflector->getDefault();
$this->isOptional = $this->defaultValue !== null;
$this->isPassedByReference = $reflector->isByReference();
Expand Down
11 changes: 8 additions & 3 deletions models/PropertyDoc.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,23 +70,28 @@ public function __construct($reflector = null, $context = null, $config = [])

$hasInheritdoc = false;
foreach ($this->tags as $tag) {
if ($tag->getName() === 'inheritdoc') {
$hasInheritdoc = true;
}
if ($tag instanceof Var_) {
$this->type = (string) $tag->getType();
$this->types = $this->splitTypes($tag->getType());

$this->description = StringHelper::mb_ucfirst($tag->getDescription());
$this->shortDescription = BaseDoc::extractFirstSentence($this->description);
} elseif ($this->isInheritdocTag($tag)) {
$hasInheritdoc = true;
}
}

if (empty($this->shortDescription) && $context !== null && !$hasInheritdoc) {
$context->warnings[] = [
'line' => $this->startLine,
'file' => $this->sourceFile,
'message' => "No short description for element '{$this->name}'",
];
}

if (!$hasInheritdoc && $this->type === null) {
$this->type = (string) $reflector->getType();
$this->types = [$this->type];
}
}
}
2 changes: 1 addition & 1 deletion templates/html/ApiRenderer.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -292,7 +292,7 @@ public function renderMethodSignature($method, $context = null)

return '<span class="signature-defs">' . implode(' ', $definition) . '</span> '
. '<span class="signature-type">' . ($method->isReturnByReference ? '<b>&</b>' : '')
. ($method->returnType === null ? 'void' : $this->createTypeLink($method->returnTypes, $context)) . '</span> '
. $this->createTypeLink($method->returnTypes, $context) . '</span> '
Copy link
Contributor Author

@mspirkov mspirkov Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now there's always a type in this place.

. '<strong>' . $this->createSubjectLink($method, $method->name) . '</strong>'
. str_replace(' ', ' ', ' ( ' . implode(', ', $params) . ' )');
}
Expand Down
115 changes: 115 additions & 0 deletions tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,18 @@ <h2>Public Properties</h2>
<td><a href="https://www.php.net/language.types.string">string</a></td>
<td>Animal name.</td>
<td><a href="yiiunit-apidoc-data-api-animal-animal.html">yiiunit\apidoc\data\api\animal\Animal</a></td>
</tr>
<tr class="">
<td><a href="yiiunit-apidoc-data-api-animal-animal.html#%24propertyWithoutDoc-detail">$propertyWithoutDoc</a></td>
<td><a href="https://www.php.net/language.types.string">string</a></td>
<td></td>
<td><a href="yiiunit-apidoc-data-api-animal-animal.html">yiiunit\apidoc\data\api\animal\Animal</a></td>
</tr>
<tr class="">
<td><a href="yiiunit-apidoc-data-api-animal-animal.html#%24propertyWithoutDocAndTypeHint-detail">$propertyWithoutDocAndTypeHint</a></td>
<td></td>
<td></td>
<td><a href="yiiunit-apidoc-data-api-animal-animal.html">yiiunit\apidoc\data\api\animal\Animal</a></td>
</tr>
</table>
</div>
Expand Down Expand Up @@ -162,6 +174,11 @@ <h2>Public Methods</h2>
<td><a href="yiiunit-apidoc-data-api-animal-animal.html#render()-detail">render()</a></td>
<td>Renders animal description.</td>
<td><a href="yiiunit-apidoc-data-api-animal-animal.html">yiiunit\apidoc\data\api\animal\Animal</a></td>
</tr>
<tr class="">
<td><a href="yiiunit-apidoc-data-api-animal-animal.html#setBirthDate()-detail">setBirthDate()</a></td>
<td></td>
<td><a href="yiiunit-apidoc-data-api-animal-animal.html">yiiunit\apidoc\data\api\animal\Animal</a></td>
</tr>
</table>
</div>
Expand Down Expand Up @@ -244,6 +261,50 @@ <h2>Property Details</h2>
</div>


</div>
<div>
<div class="detail-header h3">
<a class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
<a class="tool-link hash" href="yiiunit-apidoc-data-api-animal-animal.html#%24propertyWithoutDoc-detail" title="direct link to this method"><span class="glyphicon icon-hash"></span></a>

$propertyWithoutDoc
<span class="detail-header-tag small">
public property
</span>
</div>


<div class="doc-description">

</div>

<div class="signature">
<span class="signature-defs">public</span> <span class="signature-type"><a href="https://www.php.net/language.types.string">string</a></span> <a href="yiiunit-apidoc-data-api-animal-animal.html#%24propertyWithoutDoc-detail">$propertyWithoutDoc</a> <span style="color: #0000BB"></span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">''</span>
</div>


</div>
<div>
<div class="detail-header h3">
<a class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
<a class="tool-link hash" href="yiiunit-apidoc-data-api-animal-animal.html#%24propertyWithoutDocAndTypeHint-detail" title="direct link to this method"><span class="glyphicon icon-hash"></span></a>

$propertyWithoutDocAndTypeHint
<span class="detail-header-tag small">
public property
</span>
</div>


<div class="doc-description">

</div>

<div class="signature">
<span class="signature-defs">public</span> <span class="signature-type"></span> <a href="yiiunit-apidoc-data-api-animal-animal.html#%24propertyWithoutDocAndTypeHint-detail">$propertyWithoutDocAndTypeHint</a> <span style="color: #0000BB"></span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">''</span>
</div>


</div>
</div>

Expand Down Expand Up @@ -452,6 +513,60 @@ <h2>Method Details</h2>
</div>
</div>

</div>
<div class="">
<div class="detail-header h3">
<a class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
<a class="tool-link hash" href="yiiunit-apidoc-data-api-animal-animal.html#setBirthDate()-detail" title="direct link to this method"><span class="glyphicon icon-hash"></span></a>

setBirthDate()

<span class="detail-header-tag small">
public method
</span>
</div>


<div class="doc-description">

<p><strong></strong></p>
</div>

<table class="detail-table table table-striped table-bordered table-hover">
<tr><td colspan="3" class="signature">
<span class="signature-defs">public</span> <span class="signature-type">self</span> <strong><a href="yiiunit-apidoc-data-api-animal-animal.html#setBirthDate()-detail">setBirthDate</a></strong> ( <span class="signature-type"><a href="https://www.php.net/language.types.integer">integer</a></span> <span style="color: #0000BB">$birthDate</span> )</td></tr>

<tr>
<td class="param-name-col"><span style="color: #0000BB">$birthDate</span></td>
<td class="param-type-col"><a href="https://www.php.net/language.types.integer">integer</a></td>
<td class="param-desc-col">
</td>
</tr>


</table>




<p>
<a class="btn btn-link" data-toggle="collapse" role="button" aria-expanded="false" aria-controls="collapseSetBirthDate">
Source code
</a>
</p>
<div class="collapse">
<div class="card card-body">
<pre>
<code class="hljs php language-php"><span class="hljs-keyword">public</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">setBirthDate</span><span class="hljs-params">(int $birthDate)</span>: <span class="hljs-title">self</span>
</span>{
<span class="hljs-keyword">$this</span>-&gt;birthDate = $birthDate;
<span class="hljs-keyword">return</span> <span class="hljs-keyword">$this</span>;
}
</code>
</pre>
</div>
</div>

</div>
</div>
</div>
Expand Down
Loading
Loading