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

diff --git a/maintenance/mwdoc-filter.php b/maintenance/mwdoc-filter.php
index c80981b..268ccdb 100644 (file)
--- a/maintenance/mwdoc-filter.php
+++ b/maintenance/mwdoc-filter.php
@@ -16,8 +16,22 @@ if ( PHP_SAPI != 'cli' ) {
 }
 
 $source = file_get_contents( $argv[1] );
-$regexp = '#\@var\s+([^\s]+)([^/]+)/\s+(var|public|protected|private)\s+(\$[^\s;=]+)#';
-$replac = '${2} */ ${3} ${1} ${4}';
+$regexp = '#'
+       . '\@var'
+       . '\s+'
+       // Type hint
+       . '([^\s]+)'
+       // Any text or line(s) between type hint and '/' closing the comment
+       // (includes the star of "*/")
+       . '([^/]+)'
+       . '/'
+       . '\s+'
+       . '(var|public|protected|private)'
+       . '\s+'
+       // Variable name
+       . '(\$[^\s;=]+)'
+       . '#';
+$replac = '${2}/ ${3} ${1} ${4}';
 $source = preg_replace( $regexp, $replac, $source );
 
 echo $source;