Manual:mwdoc-filter.php
| MediaWiki version: | ≥ 1.20 |
| MediaWiki file: mwdoc-filter.php | |
|---|---|
| Location: | maintenance/ |
| Source code: | master • 1.43.0 • 1.42.4 • 1.39.11 |
| Classes: | Find code • Find documentation |
Details
[edit]mwdoc-filter.php file is a Doxygen filter to show correct member variable types in documentation.
It has been adapted for MediaWiki to resolve various bugs we experienced from using Doxygen with our coding conventions:
- We want to allow documenting class members on a single line by documenting them as
/** @var SomeType Description here., and in long-form as ā/** * Description here. * @var SomeType
- PHP does not support native type-hinting of class members. Instead, we document that using
@varin the doc blocks above it. However, Doxygen only supports parsing this from executable code. We achieve this by having the this script filter take the typehint from the doc block and insert it into the source code in front of$myvar, likeprotected SomeType $myvar. This result is technically invalid PHP code, but Doxygen understands it this way.
Options/Arguments
[edit]This script accepts the path of a PHP file as an argument.
Usage
[edit]php maintenance/run.php mwdoc-filter file
In MediaWiki version 1.39.10 and earlier, you must invoke maintenance scripts using
php maintenance/scriptName.php instead of php maintenance/run.php scriptName.ABC.php
<?php
class ABC {
/** @var array[] Description 1 */
private $a = [];
/** @var int Description 2 */
private $b;
/** @var ActorStoreFactory Description 3 */
private $c;
}
Terminal
$ php maintenance/run.php mwdoc-filter ABC.php
<?php
class ABC {
/** Description 1 */
private array[] $a = [];
/** Description 2 */
private int $b;
/** Description 3 */
private ActorStoreFactory $c;
}