MWDoxygenFilter.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Maintenance;
 
class MWDoxygenFilter {
    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;
    }
}
 
class_alias( MWDoxygenFilter::class, 'MWDoxygenFilter' );