30cb97d4a9e8bc87086baf809041a0c0a7f2e831
3 * Copyright (C) 2012 Tamas Imrei <tamas.imrei@gmail.com> https://virtualtee.blogspot.com/
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
21 * @ingroup Maintenance
22 * @phan-file-suppress PhanInvalidCommentForDeclarationType False negative about about `@var`
23 * @phan-file-suppress PhanUnextractableAnnotation False negative about about `@var`
27 * Doxygen filter to show correct member variable types in documentation.
30 * <https://virtualtee.blogspot.co.uk/2012/03/tip-for-using-doxygen-for-php-code.html>
32 * Improved to resolve various bugs and better MediaWiki PHPDoc conventions:
34 * - Insert variable name after typehint instead of at end of line so that
35 * documentation text may follow after `@var Type`.
36 * - Insert typehint into source code before $variable instead of inside the comment
37 * so that Doxygen interprets it.
38 * - Strip the text after `@var` from the output to avoid Doxygen warnings about bogus
39 * symbols being documented but not declared or defined.
41 * @internal For use by maintenance/mwdoc-filter.php
42 * @ingroup Maintenance
44 class MWDoxygenFilter
{
46 * @param string $source Original source code
47 * @return string Filtered source code
49 public static function filter( $source ) {
50 $tokens = token_get_all( $source );
51 $buffer = $bufferType = null;
53 foreach ( $tokens as $token ) {
54 if ( is_string( $token ) ) {
55 if ( $buffer !== null && $token === ';' ) {
56 // If we still have a buffer and the statement has ended,
57 // flush it and move on.
59 $buffer = $bufferType = null;
64 list( $id, $content ) = $token;
67 // Escape slashes so that references to namespaces are not
68 // wrongly interpreted as a Doxygen "\command".
69 $content = addcslashes( $content, '\\' );
70 // Look for instances of "@var Type" not followed by $name.
71 if ( preg_match( '#@var\s+([^\s]+)\s+([^\$]+)#s', $content ) ) {
72 $buffer = preg_replace_callback(
73 // Strip the "@var Type" part and remember the type
74 '#(@var\s+)([^\s]+)#s',
75 function ( $matches ) use ( &$bufferType ) {
76 $bufferType = $matches[2];
87 if ( $buffer !== null ) {
89 $output .= "$bufferType $content";
90 $buffer = $bufferType = null;
97 if ( $buffer !== null ) {