It's a parctice that dates back to 2006 when the API was first written, and frankly isn't covered by the coding conventions. Same thing with the docblocks, they're all copypasted with some bits changed and don't even make sense if you look at them in the genereated code docs.
I don't feel that any of us depend on this anymore (get a better IDE), so in the inerest of consistancy it's time we said goodbye to it.
Start of this bug, fleshed out base code implemented, plus a few key modules (will finish rest up soon)
Tweaked/improved/updated some documentation as I went through also
* Introduced a "cache mode" concept to simplify the header generation code, and to avoid odd results when conflicting cache header requests are received from submodules, or at least to formalise the handling of such cases.
* Made the cache mode private by default, so that code written in ignorance of caching tends to be safe. If different query modules are used in a single request, private caching is preferred over public caching.
* Removed the "must-revalidate" option from all CC headers, this is really specific to page views with a hacked squid in front, I don't think it's applicable here.
* Made the watchlist module private. This is really the definition of private data. There's nothing in the HTTP spec that says the URL for a CC:public request is private and can't be leaked. CC:private provides protection against unknown proxy behaviour.
* In ApiQueryAllmessages: avoid calling $wgLang->getCode() to check if it's necessary to make a new $wgLang when lang= is specified, since this is the only thing that unstubs $wgUser.
* Removed "FIXME: should this check $user instead of $wgUser?" Answer is no.
"I wouldn't object to stylizing the API code to bring it in line with
the rest of MW on principle, but I'm not gonna bother myself." --Roan
<http://www.mediawiki.org/wiki/Special:Code/MediaWiki/60657#c5108>
If you're seeing this commit in blames, tell your blame tool to ignore
whitespace, e.g., git blame -w or svn blame -x -w.
* Instead of hiding read-restricted modules, throw an error when a user without read rights tries to use them
* Do the same for write modules when $wgEnableWriteAPI is false
* Indicate whether a module needs read or write rights in action=help and action=paraminfo
* BREAKING CHANGE: action=purge now requires write rights and, for anonymous users, a POST request
Caused this warning (harmless in practice):
PHP Warning: Missing argument 3 for CentralAuthHooks::onUserLogoutComplete() in /usr/local/apache/common-local/php-1.5/extensions/CentralAuth/CentralAuthHooks.php on line 217
Doxygen documentation update:
* Changed alls @addtogroup to @ingroup. @addtogroup adds the comment to the group description, but doesn't add the file, class, function, ... to the group like @ingroup does. See for example http://svn.wikimedia.org/doc/group__SpecialPage.html where it's impossible to see related files, classes, ... that should belong to that group.
* Added @file to file description, it seems that it should be explicitely decalred for file descriptions, otherwise doxygen will think that the comment document the first class, variabled, function, ... that is in that file.
* Removed some empty comments
* Removed some ?>
Added following groups:
* ExternalStorage
* JobQueue
* MaintenanceLanguage
One more thing: there are still a lot of warnings when generating the doc.
* Refactored ApiDelete to use the new dieUsageMsg() system
* Adding some more messages to ApiBase::$messageMap
* Also using dieUsageMsg() for API-related errors in ApiRollback
* Removing 'lo' prefix for ApiLogout as it doesn't have any parameters anyway
