The syntax highlighting applied to the XML format is not all that great,
and applying it to other formats is just wrong. Instead of doing it
ourselves, let's just add a hook and let Extension:SyntaxHighlight_GeSHi
do it for us.
But for that to work, we have to add RL support to the pretty-printed
output, which means OutputPage. At the same time, lets internationalize
the header.
Bug: 65403
Change-Id: I04b1a3842abdf1fb360c54aa7164fc7cd2e50f4b
The existing API help, formatted as basically a plain-text document
embedded in XML and with a little bolding and a few links
syntax-highlighted in after the fact, works ok for experienced programmers
but isn't at all newbie-friendly. Further, all the help is hard-coded in
English, which isn't very friendly to non-English speakers.
So let's rewrite it. The help text is now obtained from i18n messages
and output in HTML, with the default display consisting of help for a
single module with links to help for other modules. This, of course,
necessitates deprecating many of the existing help-related methods and
hooks and replacing them with new ones, but backwards compatibility is
maintained for almost everything.
At the same time, action=paraminfo also needs to support the
'description' and other help-related fields being output in wikitext or
HTML, and I11cb063d (to access all modules via the 'modules' parameter
instead of having 'modules', 'formatmodules', 'querymodules', and so on)
is folded in.
And we also add Special:ApiHelp. When directly accessed, it simply
redirects to api.php with appropriate parameters. But it's also
transcludable to allow up-to-date API help text to be included within
the on-wiki documentation.
Note this patch doesn't actually add i18n messages for any API modules
besides ApiMain and ApiHelp. That will come in a followup patch, but for
the moment the backwards-compatibility code handles them nicely.
While we're messing with the documentation, we may as well add the
"internal" flag requested in bug 62905 (although the 'includeinternal'
parameter it also requests doesn't make much sense anymore) and a
"deprecated" flag that's needed by several modules now.
Bug: 30936
Bug: 38126
Bug: 42343
Bug: 45641
Bug: 62905
Bug: 63211
Change-Id: Ib14c00df06d85c2f6364d83b2b10ce34c7f513cc
* Separate client-visible and internal release notes, because there are
a lot of both and will be more coming up
* Correct errors in release notes
* Add detail on token changes to release notes
* List deprecated API classes and methods in release notes
* Add missing @deprecated on ApiFormat* classes
Change-Id: I577f3c8b9182f1625470c8bc52d3bdfe5d623d81
While it doesn't take a lot to maintain most of these, there is some
effort needed (e.g. wddx was breaking with HHVM). None have much if any
usage that seems likely to be actual code of some sort, and humans
should be able to read the jsonfm format as easily as dbgfm, dumpfm, or
txtfm.
Change-Id: I4e3d2ef59d4306756b289a4be46caef7d359ccef
API was using SVN's version keyword which GIT does not support.
All related methods were either removed, or for those that
could have been used from extensions, emptied out.
api.php?version now shows unrecognized param warning.
Change-Id: I910ca1448ed2ed697ac19b17c486d130aa1d7e03
The description for format=yaml in the auto-generated docs is coming out
as "Output data in YAML formatOutput data in JSON format". That needs
fixing.
Change-Id: I20185fba6b70cc995a41eb6f42565da4cc7c338d
Doxygen choke on text enclosed by '<' and '>' since it tries to
interpret them as HTML or XML elements. This patch adds double quotes
in includes/api/*.php files around the two following strings:
<Firstname>.<Lastname>@gmail.com
<Firstname><Lastname>@gmail.com
Which becomes:
"<Firstname>.<Lastname>@gmail.com"
"<Firstname><Lastname>@gmail.com"
Tested locally, it prevents doxygen 1.8.0 related warnings.
Change-Id: I36d82eb3fd4989ee3ffc65b0b527b83711d1ba69
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.
* (bug 28591) Update/replace/supplement spyc (YAML parsing library)
* YAML API output is now 1.2 compliant, using JSON as the formatter
YAML 1.2 spec is a JSON subset - "The primary objective of this revision is to bring YAML into compliance with JSON as an official subset. YAML 1.2 is compatible with 1.1 for most practical applications - this is a minor revision." [1] Per discussion with Tim, switch YAML to use the JSON formatter
Was originally going to delete the ApiFormatYaml per Tim, but class needed to keep nicer (and apparent) output in API help page
Hence made subclass ApiFormatJson, minimal method overriding
spyc.php deleted from libs
[1] http://www.yaml.org/spec/1.2/spec.html#id2803629
"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.
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.
* Add @addtogroup tags to various classes, to try and group conceptually-related classes together.
* Add brief descriptions to various Special pages, thanks to Phil Boswell.
* Moving some docs to be right above the classes they represent, so that they are picked up.
