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.

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.

In T90528#1135583, @Ciencia_Al_Poder wrote:

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?

In T90528#1136501, @Anomie wrote:

In T90528#1135583, @Ciencia_Al_Poder wrote:

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:

• removal of some values for format (https://lists.wikimedia.org/pipermail/mediawiki-api-announce/2014-August/000065.html)
• removal of values for 'modules' / 'querymodules'.

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.

In T90528#1139830, @jayvdb wrote:

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.

In T90528#1140517, @RobinHood70 wrote:

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.

In T90528#1140525, @Anomie wrote:

In T90528#1139830, @jayvdb wrote:

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?

In T90528#1140604, @Ricordisamoa wrote:

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?

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.

In T90528#1140624, @Anomie wrote:

In T90528#1140604, @Ricordisamoa wrote:

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.

Just checking, what's the current state here! Taking the example of maybe the automated documentation available for a popular module via Special:ApiHelp:

• Default value and their type are not available for some parameters
• Deprecated parameters are listed, but a brief description goes missing
• Information about when a parameter was introduced in, deprecated or removed in still goes missing.

All the above causes the need to document them again in a separate section.

As part of T198916, for one of the pages, for now, I've tried to visually distinguish the parameters removed, deprecated, etc (TODO still to use ApiParam for this)

Is it even feasible or a good idea to obtain the information in a similar format via Special:ApiHelp? Would this T90528#1136501 be still the right approach?

In T90528#4572922, @srishakatux wrote:

Taking the example of maybe the automated documentation available for a popular module via Special:ApiHelp:

• Default value and their type are not available for some parameters

Note that some parameters don't have a default value, and we don't bother saying "Default: false" for boolean parameters because of how they work like HTML checkboxes.

We also don't display types when the type is "any string" (internally, 'NULL', 'string', or 'text') because it doesn't provide useful information to specify that any string is valid input.

• Deprecated parameters are listed, but a brief description goes missing

Again, examples please. Code-wise the brief description is still there, but sometimes it is rewritten to point to the replacement rather than re-describing the functionality.

Is it even feasible or a good idea to obtain the information in a similar format via Special:ApiHelp? Would this T90528#1136501 be still the right approach?

Keep in mind that ApiHelp is supposed to be more of a reference card than a user manual.

We could include "introduced" and "deprecated" easily enough, as mentioned in T90528#1136501, although the output might get a bit cluttered. Also probably PARAM_DEPRECATED's value should work like the values in the PARAM_DEPRECATED_VALUES array, so instead a new version-number PARAM would be needed for that too.

"Removed" (and "changed" in general) seem likely to be more problematic, and IMO would be better served by a changlog of some sort in the wiki user manual.

BTW, as for the format, are those colored tags colorblind-usable?