Last modified: 2012-04-16 09:16:04 UTC

Wikimedia Bugzilla is closed!

Wikimedia migrated from Bugzilla to Phabricator. Bug reports are handled in Wikimedia Phabricator.
This static website is read-only and for historical purposes. It is not possible to log in and except for displaying bug reports and their history, links might be broken. See T31265, the corresponding Phabricator task for complete and up-to-date bug report information.
Bug 29265 - Mediawiki API documentation incomplete
Mediawiki API documentation incomplete
Status: RESOLVED FIXED
Product: MediaWiki
Classification: Unclassified
API (Other open bugs)
unspecified
All All
: Lowest normal (vote)
: ---
Assigned To: Roan Kattouw
:
Depends on:
Blocks: documentation
  Show dependency treegraph
 
Reported: 2011-06-03 16:51 UTC by Smallman
Modified: 2012-04-16 09:16 UTC (History)
5 users (show)

See Also:
Web browser: ---
Mobile Platform: ---
Assignee Huggle Beta Tester: ---


Attachments

Description Smallman 2011-06-03 16:51:31 UTC
The Mediawiki API documentation at 
http://en.wikipedia.org/w/api.php

is incomplete.

It should mention that there is a "MediaWiki-API-Error" header returned with erroneous requests.

There's also no documentation of how to use the maxlag parameter.
Comment 1 Sam Reed (reedy) 2011-06-03 17:41:31 UTC
Maxlag is documented at the top of the page
Comment 2 Brion Vibber 2011-06-03 18:14:15 UTC
Maxlag appears to be documented only as "maxlag - Maximum lag" which I'm not sure is very helpful. :)

There is a prominent link to http://www.mediawiki.org/wiki/API ... but there's no obvious link to maxlag info there either.

If you search on mediawiki.org you can turn up this page:

http://www.mediawiki.org/wiki/Manual:Maxlag_parameter

Perhaps we can have the help link to some of these detail pages directly?
Comment 3 Sam Reed (reedy) 2011-06-03 23:02:26 UTC
(In reply to comment #2)
> Maxlag appears to be documented only as "maxlag - Maximum lag" which I'm not
> sure is very helpful. :)
> 
> There is a prominent link to http://www.mediawiki.org/wiki/API ... but there's
> no obvious link to maxlag info there either.
> 
> If you search on mediawiki.org you can turn up this page:
> 
> http://www.mediawiki.org/wiki/Manual:Maxlag_parameter
> 
> Perhaps we can have the help link to some of these detail pages directly?

People should think themselves lucky they get any documentation at ALL! =D
Comment 4 Smallman 2011-06-04 00:59:10 UTC
@Reedy

The lack of documentation is abhorrent. This isn't a half-baked alpha API, and neither is this a proprietary API...this is supposed to be FOSS.

A public API isn't meant to be an exercise in reverse engineering...
Comment 5 Sam Reed (reedy) 2011-06-04 10:05:06 UTC
(In reply to comment #4)
> @Reedy
> 
> The lack of documentation is abhorrent. This isn't a half-baked alpha API, and
> neither is this a proprietary API...this is supposed to be FOSS.
> 
> A public API isn't meant to be an exercise in reverse engineering...

That at best, is slightly an overstatement.

The API pro-rata to most of the project is well documented, both with the internal and the more external facing documented.

Granted, it's not perfect, but what FOSS project is. When you don't pay people to write documentation, chances are, they won't.

This seems very reverse to what most people have said, with it often being reasonably well congratulated of it being there.

Even when I was using 3-4 years ago as just a consumer, I rarely had any difficulties, usually it was when using strange parameter combinations, but it was worked out.

Similarly, if it is "so abhorrent", why don't we have more complaints of things being bad? Usually people have nitpicks over little bits and pieces, but it's never "OMG THE DOCUMENTATION IS SO BAD I CANT FUCKING USE THIS"


Unfortunately we are both not mind readers, and also mixed ability end user consumers. We can't work out what you think is wrong, so unless people tell us, it's a wild stab in the dark.

And on that the only issues you seem to bring up, is 1 poorly documented parameter, and the fallback "error" which brings you to the help page in a lot of cases. I've no idea how you get from 2 omissions/errors
Comment 6 Sam Reed (reedy) 2011-06-04 11:31:35 UTC
Maxlag documentation fleshed out on API inbuilt help in r89461
Comment 8 Sam Reed (reedy) 2011-06-05 15:10:36 UTC
r89505 adds the information about erroneous requests to the API help output
Comment 9 Mark A. Hershberger 2011-06-10 20:49:10 UTC
closing.  Please refrain from reopening unless you have some specific thing that you think needs to be documented better and that isn't addressed by the above comments.

Note You need to log in before you can comment on or make changes to this bug.


Navigation
Links