Page MenuHomePhabricator

$wgResourceModules documentation is incomplete
Closed, ResolvedPublic

Description

I was looking how to include config variables with modules and noticed the documentation for $wgResourceModules is very incomplete.

For example https://www.mediawiki.org/wiki/Manual:$wgResourceModules does not mention noflip, targets or templates or packageFiles. The documentation in DefaultSettings.php is even less complete.

These options are mentioned in docs/extension.schema.v2.json, but even there it doesn't really explain how to use packageFiles.

Currently best documentation seems to be the doc for constructor in includes/resourceloader/ResourceLoaderFileModule.php, but even that fails to mention noflip.

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald Transcript
Krinkle triaged this task as Medium priority.
Krinkle added a subscriber: Krinkle.

We've documented packageFiles at https://www.mediawiki.org/wiki/ResourceLoader/Package_modules.

I'll make sure to link this from various places.

For the other properties, those are primarily documented in-place with Doxygen (the wiki page is essentially an outdated copy of that).

I'll make sure both are up to date, possibly by linking one to the other so as to not need to keep these and all other config/class docs in two places.

I added the missing options to https://www.mediawiki.org/wiki/Manual:$wgResourceModules
page and sorted them by key name. Should I also sort the key names in the JSON file
(docs/extension.schema.v2.json)?

Do we need a more comprehensive example in DefaultSettings.php? Or just on the page above?

@holger.knust I think we may want to move the (now updated) docs from the wiki page to DefaultSettings.php indeed. We can then remove replace the old comment at ResourceLoaderFileModule.php with a @see reference to $wgResourceModules, and once merged update the wiki to refer to doc.wikimedia.org. That's the general pattern I've followed for most docs in components Perf Team maintains for its classes and site config variables. (Using wiki pages only for high-level architecture and user manuals for instaling or upgrading something).

This has the benefit of being maintained in context with the code (usually updated in the same commit), and naturally reviewed/published in a versioned manner (e.g. docs for mediawiki/objectcache@MW 1.33.1). It's a trade off for sure though, so I don't mind having this link the other way around for now (from DefaulSettings/ResourceLoaderFileModule to the wiki).

Change 583476 had a related patch set uploaded (by Holger Knust; owner: Holger Knust):
[mediawiki/core@master] mediawiki: $wgResourceModules documentation is incomplete

https://gerrit.wikimedia.org/r/583476

Change 583476 merged by jenkins-bot:
[mediawiki/core@master] resourceloader: Add more $wgResourceModules documentation

https://gerrit.wikimedia.org/r/583476

It seems still impossible to figure out since what version has packageFiles been supported. There is no mention in HISTORY or RELEASE-NOTES and quick code search does not bring up any @since tags. The answer seems to be 1.33 based on https://gerrit.wikimedia.org/r/c/mediawiki/core/+/471370

Change 643785 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] resourceloader: Improve wgResourceModules documentation

https://gerrit.wikimedia.org/r/643785

Krinkle claimed this task.
Krinkle moved this task from Doing (old) to Blocked (old) on the Performance-Team board.
Krinkle added a subscriber: holger.knust.

Change 643785 merged by jenkins-bot:
[mediawiki/core@master] resourceloader: Improve wgResourceModules documentation

https://gerrit.wikimedia.org/r/643785