This interesting task makes me wonder whether api.php itself should be also demoted, promoting the API transclusion in wiki pages as the primary means to check API documentation.

Theoretical benefits of this approach:

• Searchable content.
• No need to theme api.php, since the docs (being wiki pages) will acquire the theme of the wiki.

If you think this idea is worth discussing further, I can create a new task for it.

In T89318#1046182, @Qgil wrote:

This interesting task makes me wonder whether api.php itself should be also demoted, promoting the API transclusion in wiki pages as the primary means to check API documentation.

If the on-wiki doc writers want to avoid mentioning it that's fine with me, but documentation on api.php is IMO too useful to bot and script developers to go away.

To be clear, I'm only suggesting that the exact api.php documentation is displayed via transclusion in wiki pages. Same content, only searchable and themed.

In T89318#1046182, @Qgil wrote:

[promote] API transclusion in wiki pages as the primary means to check API documentation.

Theoretical benefits of this approach:

• Searchable content.
• No need to theme api.php, since the docs (being wiki pages) will acquire the theme of the wiki.

It's an interesting idea. There are two ways to navigate from transcluded API docs:

1. The wiki navigation, e.g. the {{API}} TOC template
2. The "(main | query | extracts)" crumbtrail below the transcluded apihelp-header.

As well as skinning, the generated documentation lacks a TOC and search. These are all doable, but if developers mostly consume the generated doc on-wiki, it reduced the priority of improving the experience of browsing api.php?action=help.

We ought to get metrics of how developers use the API documentation.

The generated documentation does not include historical information, and should not replace existing documentation for the core API. It can be a temporary substitute for hand written well written documentation, however the effort should instead be put into building tools which pre-create basic wiki documentation and syncronising the wiki documentation after each release to add/deprecate/remove submodules/parameters/etc that have changed.

In T89318#1131276, @jayvdb wrote:

The generated documentation does not include historical information.

This is incorrect. Our generated documentation can and will have far better historical coverage than our wiki pages. The wiki has, to my knowledge, never been fragmented by version. Some higher level documentation pages cover older versions in side notes but never for entire chapters, or for API documentation.

Our generated documentation on the other hand has naturally been generated since MediaWiki 1.19. We've had the generator since then. Branches that are even older are no longer supported and no longer have releases that would automatically trigger a documentation build. However we could easily enable a one-time run for legacy branches like 1.18, 1.17 or earlier. As of writing, it already goes back 5 releases.

• https://doc.wikimedia.org/mediawiki-core/REL1_19/php/html/
• https://doc.wikimedia.org/mediawiki-core/REL1_22/php/html/
• https://doc.wikimedia.org/mediawiki-core/REL1_23/php/html/
• https://doc.wikimedia.org/mediawiki-core/REL1_24/php/html/
• https://doc.wikimedia.org/mediawiki-core/master/php/html/

In T89318#1134471, @Krinkle wrote:

In T89318#1131276, @jayvdb wrote:

The generated documentation does not include historical information.

This is incorrect. Our generated documentation can and will have far better historical coverage than our wiki pages.

"can and will have" (future tense and wishful thinking) does not contradict "does not" (present tense).

Regarding versioning, that discussion probably belongs on T90528.

In T89318#1134480, @jayvdb wrote:

In T89318#1134471, @Krinkle wrote:

This is incorrect. Our generated documentation can and will have far better historical coverage than our wiki pages.

"can and will have" (future tense and wishful thinking) does not contradict "does not" (present tense).

Poor phrasing on my part, but you're missing the rest of my comment. I meant "does and always will have". We've had historical coverage in generated documentation for several years now.

In T89318#1131276, @jayvdb wrote:

The generated documentation does not include historical information

Thanks for commenting on Task T90528. We should add module version parameters to {{Api help}} in the interim.

and should not replace existing documentation for the core API.

When people have carefully indicated the version of every method and parameter, it's a shame to lose it; I've updated this task's description to discourage this. https://www.mediawiki.org/wiki/Wikibase/API made me add this task, it's a mass of unversioned out-of-date copy-paste that now has many static translations. It's not core API with a lot of history, are you opposed to using {{Api help}} in it?

It can be a temporary substitute for hand written well written documentation, however the effort should instead be put into building tools which pre-create basic wiki documentation and syncronising the wiki documentation after each release to add/deprecate/remove submodules/parameters/etc that have changed.

That sounds like a ton of work. I appreciate volunteers taking it on.
Meanwhile the API to Wikimedia sites evolves constantly, every two weeks. We need to handle latest vs. versions in all generated doc, so I mentioned this in T93026.

In T89318#1134482, @Krinkle wrote:

We've had historical coverage in generated documentation for several years now.

Do you mean historical coverage in *Doxygen* generated documentation?

If so, how is that relevant to Special:ApiHelp? Is Special:ApiHelp going to load Doxygen?