From 3fba44335a3f9ca0dad7babda694a36ab090f832 Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinklemail@gmail.com>
Date: Sat, 30 Aug 2014 18:10:26 +0200
Subject: [PATCH] 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
---
 maintenance/mwdoc-filter.php | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/maintenance/mwdoc-filter.php b/maintenance/mwdoc-filter.php
index c80981b56d..268ccdbcb5 100644
--- 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;
-- 
2.20.1