doxygen: Fix trailing star in class member descriptions
authorTimo Tijhof <krinklemail@gmail.com>
Sat, 30 Aug 2014 16:10:26 +0000 (18:10 +0200)
committerKrinkle <krinklemail@gmail.com>
Tue, 23 Sep 2014 03:07:12 +0000 (03:07 +0000)
commit3fba44335a3f9ca0dad7babda694a36ab090f832
tree4077f7d3644122ae5692116e2ba6a023e9218161
parent1a239219eebbb53b42d63cb27c20cf0c9a756809
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