Page MenuHomeWickedGov Phorge
Files F4129092

MWDoxygenFilter.php
No OneTemporary
Actions

Size
4 KB
Referenced Files
None
Subscribers
None

MWDoxygenFilter.php
View Options

<?php
/**
* Copyright (C) 2012 Tamas Imrei <tamas.imrei@gmail.com> https://virtualtee.blogspot.com/
*
* @license GPL-2.0-or-later
* @file
* @ingroup Maintenance
*/
namespace MediaWiki\Maintenance;
/**
* Doxygen filter to show correct member variable types in documentation.
*
* Based on
* <https://virtualtee.blogspot.co.uk/2012/03/tip-for-using-doxygen-for-php-code.html>
*
* 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
* `/**\n * Description here.\n * @var SomeType`.
*
* - PHP does not support native type-hinting of class members. Instead, we document
* that using `@var` in the doc blocks above it. However, Doxygen only supports
* parsing this from executable code. We achieve this by having the below filter
* take the typehint from the doc block and insert it into the source code in
* front of `$myvar`, like `protected SomeType $myvar`. This result is technically
* invalid PHP code, but Doxygen understands it this way.
*
* @internal For use by maintenance/mwdoc-filter.php
* @ingroup Maintenance
*/
class MWDoxygenFilter {
/**
* @param string $source Original source code
* @return string Filtered source code
*/
public static function filter( $source ) {
$tokens = token_get_all( $source );
$buffer = null;
$output = '';
foreach ( $tokens as $token ) {
if ( is_string( $token ) ) {
if ( $buffer !== null && $token === ';' ) {
// If we still have a buffer and the statement has ended,
// flush it and move on.
$output .= $buffer['raw'];
$buffer = null;
}
$output .= $token;
continue;
}
[ $id, $content ] = $token;
switch ( $id ) {
case T_DOC_COMMENT:
// Escape slashes so that references to namespaces are not
// wrongly interpreted as a Doxygen "\command".
$content = addcslashes( $content, '\\' );
// Look for instances of "@var SomeType".
if ( preg_match( '#@var\s+\S+#', $content ) ) {
$buffer = [ 'raw' => $content, 'desc' => null, 'type' => null, 'name' => null ];
$buffer['desc'] = preg_replace_callback(
// Strip "@var SomeType" part, but remember the type and optional name
'#@var\s+(\S+)(\s+)?(\S+)?#',
static function ( $matches ) use ( &$buffer ) {
$buffer['type'] = $matches[1];
$buffer['name'] = $matches[3] ?? null;
return ( $matches[2] ?? '' ) . ( $matches[3] ?? '' );
},
$content
);
} else {
$output .= $content;
}
break;
case T_VARIABLE:
// Doxygen requires class members to be documented in one of two ways:
//
// 1. Fully qualified:
// /** @var SomeType $name Description here. */
//
// These result in the creation of a new virtual node called $name
// with the specified type and description. The real code doesn't
// even need to exist in this case.
//
// 2. Contextual:
// /** Description here. */
// private SomeType? $name;
//
// In MediaWiki, we are mostly like #1 but without the name repeated:
// /** @var SomeType Description here. */
// private $name;
//
// These emit a warning in Doxygen because they are missing a variable name.
// Convert these to the "Contextual" kind by stripping ""@var", injecting
// type into the code, and leaving the description in-place.
if ( $buffer !== null ) {
if ( $buffer['name'] === $content ) {
// Fully qualitied "@var" comment, leave as-is.
$output .= $buffer['raw'];
$output .= $content;
} else {
// MW-style "@var" comment. Keep only the description and transplant
// the type into the code.
$output .= $buffer['desc'];
$output .= "{$buffer['type']} $content";
}
$buffer = null;
} else {
$output .= $content;
}
break;
default:
if ( $buffer !== null ) {
$buffer['raw'] .= $content;
$buffer['desc'] .= $content;
} else {
$output .= $content;
}
break;
}
}
return $output;
}
}
/** @deprecated class alias since 1.43 */
class_alias( MWDoxygenFilter::class, 'MWDoxygenFilter' );

File Metadata

Mime Type
text/x-php
Expires
Wed, Aug 19, 09:36 (2 w, 4 d ago)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
bf/91/06593a6a690a9372ada932b23f21
Default Alt Text
MWDoxygenFilter.php (4 KB)

Event Timeline