wiki.techinc.nl/maintenance/mwdoc-filter.php

49 lines
1.1 KiB
PHP
Raw Normal View History

<?php
/**
* Doxygen filter to show correct member variable types in documentation.
*
* Should be filled in doxygen INPUT_FILTER as "php mwdoc-filter.php"
*
* Original source code by Goran Rakic
* http://blog.goranrakic.com/
* http://stackoverflow.com/questions/4325224
*
* @file
*/
if ( PHP_SAPI != 'cli' ) {
die( "This filter can only be run from the command line.\n" );
}
$source = file_get_contents( $argv[1] );
doxygen: Fix trailing star in class member descriptions Currently lots of member descriptions in generated Doxygen pages have a trailing star or even just a star as their description. This is due to the regex we use to *change* the code before Doxygen is given the code. This filter script translates the code to be invalid PHP that looks more like Java's strongly typed class members. The regex has been broken up into pieces for better readabilty but not changed in any way. The replacement is where the fix was made. Here we now replace with "${2}/" instead of "${2} */". Using ResourceLoader.php as example: $ php maintenance/mwdoc-filter.php includes/resourceloader/ResourceLoader.php == Before == Filtered code: /** @var array Module name/ResourceLoaderModule object pairs */ protected $modules = array(); /** Associative mapping ... * */ protected array $moduleInfos = array(); /** $config * */ private Config $config; /** * Associative array mapping framework ids * like array( 'ext.foo.tests', .. ) * */ protected array $testModuleNames = array(); /** @var array E.g. array( 'http://.../load.php' ) */ protected $sources = array(); /** * */ protected bool $hasErrors = false; Rendering currently at https://doc.wikimedia.org/mediawiki-core/master/php/html/classResourceLoader.html bool $hasErrors = false * array $moduleInfos = array() Associative mapping ... *. $modules = array() $sources = array() array $testModuleNames = array() Associative array mapping framework ids like array( 'ext.foo.tests', . Config $config $config * Note the stray stars in hasErrors, moduleInfos and $config. $testModuleNames doesn't have it because it has a multi-line block comment and presumably Doxygen tolerates spaces in the final star sequence if it's on its own line. == After == Filtered code: /** @var array Module name/ResourceLoaderModule object pairs */ protected $modules = array(); /** Associative mapping ... */ protected array $moduleInfos = array(); /** $config */ private Config $config; /** * Associative array mapping framework ids * like array( 'qunit' => array( 'ext.foo.tests', .. ), .. ) */ protected array $testModuleNames = array(); /** @var array E.g. array( 'http://.../load.php' ) */ protected $sources = array(); /** */ protected bool $hasErrors = false; Change-Id: Id7c307dc2911ef4f1a6c2ca566c6b48735b763d7
2014-08-30 16:10:26 +00:00
$regexp = '#'
. '\@var'
. '\s+'
// Type hint
. '([^\s]+)'
. '\s+'
doxygen: Fix trailing star in class member descriptions Currently lots of member descriptions in generated Doxygen pages have a trailing star or even just a star as their description. This is due to the regex we use to *change* the code before Doxygen is given the code. This filter script translates the code to be invalid PHP that looks more like Java's strongly typed class members. The regex has been broken up into pieces for better readabilty but not changed in any way. The replacement is where the fix was made. Here we now replace with "${2}/" instead of "${2} */". Using ResourceLoader.php as example: $ php maintenance/mwdoc-filter.php includes/resourceloader/ResourceLoader.php == Before == Filtered code: /** @var array Module name/ResourceLoaderModule object pairs */ protected $modules = array(); /** Associative mapping ... * */ protected array $moduleInfos = array(); /** $config * */ private Config $config; /** * Associative array mapping framework ids * like array( 'ext.foo.tests', .. ) * */ protected array $testModuleNames = array(); /** @var array E.g. array( 'http://.../load.php' ) */ protected $sources = array(); /** * */ protected bool $hasErrors = false; Rendering currently at https://doc.wikimedia.org/mediawiki-core/master/php/html/classResourceLoader.html bool $hasErrors = false * array $moduleInfos = array() Associative mapping ... *. $modules = array() $sources = array() array $testModuleNames = array() Associative array mapping framework ids like array( 'ext.foo.tests', . Config $config $config * Note the stray stars in hasErrors, moduleInfos and $config. $testModuleNames doesn't have it because it has a multi-line block comment and presumably Doxygen tolerates spaces in the final star sequence if it's on its own line. == After == Filtered code: /** @var array Module name/ResourceLoaderModule object pairs */ protected $modules = array(); /** Associative mapping ... */ protected array $moduleInfos = array(); /** $config */ private Config $config; /** * Associative array mapping framework ids * like array( 'qunit' => array( 'ext.foo.tests', .. ), .. ) */ protected array $testModuleNames = array(); /** @var array E.g. array( 'http://.../load.php' ) */ protected $sources = array(); /** */ protected bool $hasErrors = false; Change-Id: Id7c307dc2911ef4f1a6c2ca566c6b48735b763d7
2014-08-30 16:10:26 +00:00
// Any text or line(s) between type hint and '/' closing the comment
// (includes the star of "*/"). Descriptions containing a slash
// are not supported. Those will have to to be rewritten to have their
// description *before* the @var:
// /**
// * Description with / in it.
// * @var array
// */
// instead of:
// /**
// * @var array Description with / in it.
// */
doxygen: Fix trailing star in class member descriptions Currently lots of member descriptions in generated Doxygen pages have a trailing star or even just a star as their description. This is due to the regex we use to *change* the code before Doxygen is given the code. This filter script translates the code to be invalid PHP that looks more like Java's strongly typed class members. The regex has been broken up into pieces for better readabilty but not changed in any way. The replacement is where the fix was made. Here we now replace with "${2}/" instead of "${2} */". Using ResourceLoader.php as example: $ php maintenance/mwdoc-filter.php includes/resourceloader/ResourceLoader.php == Before == Filtered code: /** @var array Module name/ResourceLoaderModule object pairs */ protected $modules = array(); /** Associative mapping ... * */ protected array $moduleInfos = array(); /** $config * */ private Config $config; /** * Associative array mapping framework ids * like array( 'ext.foo.tests', .. ) * */ protected array $testModuleNames = array(); /** @var array E.g. array( 'http://.../load.php' ) */ protected $sources = array(); /** * */ protected bool $hasErrors = false; Rendering currently at https://doc.wikimedia.org/mediawiki-core/master/php/html/classResourceLoader.html bool $hasErrors = false * array $moduleInfos = array() Associative mapping ... *. $modules = array() $sources = array() array $testModuleNames = array() Associative array mapping framework ids like array( 'ext.foo.tests', . Config $config $config * Note the stray stars in hasErrors, moduleInfos and $config. $testModuleNames doesn't have it because it has a multi-line block comment and presumably Doxygen tolerates spaces in the final star sequence if it's on its own line. == After == Filtered code: /** @var array Module name/ResourceLoaderModule object pairs */ protected $modules = array(); /** Associative mapping ... */ protected array $moduleInfos = array(); /** $config */ private Config $config; /** * Associative array mapping framework ids * like array( 'qunit' => array( 'ext.foo.tests', .. ), .. ) */ protected array $testModuleNames = array(); /** @var array E.g. array( 'http://.../load.php' ) */ protected $sources = array(); /** */ protected bool $hasErrors = false; Change-Id: Id7c307dc2911ef4f1a6c2ca566c6b48735b763d7
2014-08-30 16:10:26 +00:00
. '([^/]+)'
. '/'
. '\s+'
. '(var|public|protected|private)'
. '\s+'
// Variable name
. '(\$[^\s;=]+)'
. '#';
$replac = '${2}/ ${3} ${1} ${4}';
$source = preg_replace( $regexp, $replac, $source );
echo $source;