Generated API Help doesn't indicate the MediaWiki versions that support a module and parameters.
Open, LowPublic

Description

@RobinHood70 commented

I think it [ Template:Api help ] 'll be great for documenting current versions of parameters, but I'm concerned that if we move to that exclusively, we'll lose a lot of the other information currently available on the page, like information on what version a parameter was introduced in, deprecated in, or removed from. That's important information for people like me who are developing bot frameworks and need to know historical information so that a bot can be universal rather than bleeding-edge only. Most of the non-MediaWiki wikis I deal with, and that I would expect my bot to be able to deal with, are still running on 1.19 and I've seen wikis running on versions as old as 1.15.

For example, the imageinfo property wiki page documents when the property was introduced and many parameters document the MediaWiki version in which they were introduced.

Spage updated the task description. (Show Details)
Spage raised the priority of this task from to Normal.
Spage added subscribers: Qgil, Anomie, RobLa and 3 others.
jayvdb added a subscriber: jayvdb.Mar 19 2015, 9:58 AM

I think T89318 is barking up the wrong tree, wasnt scoped properly before being implemented, as having at least basic historical information would be a prereq.

fwiw, there is a wiki on the Interwiki Map that is running 1.11.1

ReutersWiki:
http://glossary.reuters.com/index.php/
http://glossary.reuters.com/api.php?action=query&meta=siteinfo

There are also modules like filerepoinfo where the parameter list available is very variable, not based solely on version. see also T85153 and T74847.

Also needed is versioning information for *values* of parameters, such as the values for inprop and the prop param for other modules.

Anomie lowered the priority of this task from Normal to Low.Mar 20 2015, 2:45 PM

If this is to move forward, someone would need to do the following:

  1. Propose a plan for how exactly to represent the requested data in ApiBase, which will also involve clarification of what data exactly is to be represented.
  2. Collect and prepare historical data, either as a patch implementing #1 or in a machine-readable format from which the data-bearing portion of such a patch could be automatically generated.

We have currently in the parameter definitions metadata like parameter type, default value and if the parameter is deprecated. We could add another with information about when it was added, and expose it in api help.

Parameters that were removed could be added manually on those wiki pages.

We have currently in the parameter definitions metadata like parameter type, default value and if the parameter is deprecated. We could add another with information about when it was added, and expose it in api help.

True, but that doesn't cover when the whole module was added or "versioning information for *values* of parameters" mentioned in T90528#1131315. The complete set would seem to be:

  • A method in ApiBase to say which version the module was added.
  • A new "PARAM_VERSION" for which version the parameter was added, if not the same as above.
  • A new "PARAM_VALUE_VERSION" assoc for which version each possible value was added to the parameter, if not the same as above.
  • Maybe a new "PARAM_DYNAMIC_VALUES" boolean to indicate that the available values depend on the wiki configuration beyond "what extensions are installed".
  • We should probably change PARAM_DEPRECATED from a boolean to a version number, too, and the same for the return value of ApiBase::isDeprecated().

@jayvdb, does that seem sufficient?

We have currently in the parameter definitions metadata like parameter type, default value and if the parameter is deprecated. We could add another with information about when it was added, and expose it in api help.

True, but that doesn't cover when the whole module was added or "versioning information for *values* of parameters" mentioned in T90528#1131315. The complete set would seem to be:

  • A method in ApiBase to say which version the module was added.
  • A new "PARAM_VERSION" for which version the parameter was added, if not the same as above.
  • A new "PARAM_VALUE_VERSION" assoc for which version each possible value was added to the parameter, if not the same as above.
  • Maybe a new "PARAM_DYNAMIC_VALUES" boolean to indicate that the available values depend on the wiki configuration beyond "what extensions are installed".
  • We should probably change PARAM_DEPRECATED from a boolean to a version number, too, and the same for the return value of ApiBase::isDeprecated().

    @jayvdb, does that seem sufficient?

If not already available, it may also need metadata kept about param *value* deprecation and *removal* (i.e. post deprecation, the 'removed' value needs to be retained but not exposed by default, so the API can expose the list of 'removed'/de-activated' values.

Some example of 'meta' (api structure) values removed:

Examples of a 'real' (functional) value removed:

  • action=parse&prop=languageshtml

And values slated for removal (some are in extensions):

  • list=search prop=score and prop=hasrelated
  • meta=userinfo prop=preferencestoken
  • list=codecomments prop=revision
  • list=deletedrevs prop=token
  • list=messagecollection prop=revision
  • etc

We also need a method of documenting modules which have been removed, so that documentation doesnt disappear when modules are finally removed, post deprecation. Essentially this would mean that instead of removing API modules, they would need to be de-activated after deprecation, with their metadata maintained for documentation purposes.

An interesting case is the 'pageset' module, which iirc was a distinct module 1.15-1.24, and has been disappeared from the API already.

list=deletedrevs & prop=deletedrevs might be another useful case to model carefully in the design.

Sorry if these are already catered for in ApiBase - I didnt dig around in there to see if it has features not yet exposed and utilised.

Would splitting modules into functional and documentation submodules be a useful model here? The API itself could then remain light and fairly clean, only linking to the documentation if needed, while documentation submodules would be off to the side, accessible by the documentation routines to allow documenting the older stuff. The one concern that jumps out at me is that, depending how it's done, lazy programmers could fail to document current and new features at all. This is already a problem with the wiki documentation vs. live modules and obviously, we don't want to simply move the problem to another venue.

Another concern is how to make the documentation accessible and expandable. There's only so much you can do via programming, and moving the main part of the documentation to the module itself decreases the accessibility by Joe Blow who wants to correct typos, expand on the documentation, or present more complex things like tables and such, for easier reading. Yes, the wiki is there for that sort of thing, but moving documentation to the code and then linking it in to the wiki limits the ability to provide special formatting or add side notes within the body of the documentation itself, where it would be most useful. One possibility I can think of is to invert the logic here, and use a help style where the wiki is actually the primary source of documentation and it gets pulled in by the modules, much like how MediaWiki space is used to distribute default messages while still allowing for customization.

and *removal* (i.e. post deprecation, the 'removed' value needs to be retained but not exposed by default, so the API can expose the list of 'removed'/de-activated' values.

I was afraid you'd say something like that. Cluttering the API code with information about long-dead parameters and modules is getting well into WONTFIX territory.

Would splitting modules into functional and documentation submodules be a useful model here?

[...]

The one concern that jumps out at me is that, depending how it's done, lazy programmers could fail to document current and new features at all. This is already a problem with the wiki documentation vs. live modules and obviously, we don't want to simply move the problem to another venue.

I'd have the same concern. We killed ApiBase::getResultProperties and ApiBase::getPossibleErrors in part for this reason, and when updating extensions for the new help I saw a number of extension modules that didn't even bother to implement ApiBase::getDescription() or ApiBase::getParamDescription().

One possibility I can think of is to invert the logic here, and use a help style where the wiki is actually the primary source of documentation and it gets pulled in by the modules, much like how MediaWiki space is used to distribute default messages while still allowing for customization.

The help texts are now i18n messages, so you're there on that score.

But the api.php output is intended to be a "reference card", documenting available modules and their parameters for programmers who already mostly know what they're doing and just need the specifics. Detailed instructional content should be on the wiki, linked to from api.php but not imported.

and *removal* (i.e. post deprecation, the 'removed' value needs to be retained but not exposed by default, so the API can expose the list of 'removed'/de-activated' values.

I was afraid you'd say something like that. Cluttering the API code with information about long-dead parameters and modules is getting well into WONTFIX territory.

Agreed. What about using Git branches and the PHP tokenizer (or a fake MediaWiki instance) to get information about old parameters and modules?

Agreed. What about using Git branches and the PHP tokenizer (or a fake MediaWiki instance) to get information about old parameters and modules?

If you're saying for ApiHelp or SpecialApiHelp to do this, that's even worse. If not, what exactly are you proposing does this?

RobinHood70 added a comment.EditedMar 23 2015, 5:20 PM

Maybe rather than trying to use the PHP-side docs as primary on the wiki, we should change it to a "see live docs" link and have that as an option that you can click on if the wiki page appears to be out of date. I think that'll give us the best of both worlds: the wiki can still document all the historical info and provide any custom formatting or topic-specific notes that might be required, while the live docs can be used, as Anomie says, as a quick reference.

Agreed. What about using Git branches and the PHP tokenizer (or a fake MediaWiki instance) to get information about old parameters and modules?

If you're saying for ApiHelp or SpecialApiHelp to do this, that's even worse. If not, what exactly are you proposing does this?

A bot.