Page MenuHomePhabricator

Standardise documentation for ResourceLoader modules inside module classes
Closed, DeclinedPublic

Description

We should add some built-in documentation/listing for RL modules like we have for Api modules, extensions, and special pages.

We'll add some more metadata and i18n for modules:

  • Description message keys go into a module definition like we do with extension credits (or we could just use the module name and hardcode the pattern like we to with special page names)
  • Another key defines the origin of the module (ie: core, ext.CodeEditor, etc...) so you can tell if the code is going to disappear if an extension is uninstalled.
  • In i18n we define a block description of the module. And label names for the module groups we already have.

Then we'll add a new special page. On it we'll list all the available modules. Described by the description we added to i18n. Grouped by the group. With a few bits of extra helpful information like; Origin. Source if we implement RL2's multiple module sources. Dependencies. Top loading and the non-js css property we have a bug open to add. Has scripts? Styles? Custom implementation class?

We can probably add a list of i18n message keys inside a collapsible area. Perhaps even display it in an Allmessages table. This would allow an easy way for sites to find and customize the messages that modules use.

When we start generating documentation for extension scripts and RL modules we should also consider making it so that RL modules have enough information for the special page to link to generated documentation on the modules. For now we may want to consider documentation urls to pages like RL's Default modules page on MW.org.


Version: 1.22.0
Severity: enhancement

Details

Reference
bz46563

Event Timeline

bzimport raised the priority of this task from to Low.Nov 22 2014, 1:19 AM
bzimport set Reference to bz46563.
bzimport added a subscriber: Unknown Object (MLST).
Krinkle renamed this task from ResourceLoader: Modules should have a built-in list with details on all available modules to Standardise documentation for ResourceLoader modules inside module classes.Aug 5 2015, 12:50 AM
Krinkle set Security to None.
Krinkle removed a subscriber: wikibugs-l-list.

Interesting idea. Not a priority at the moment since our front-end code base is quite well documented with JSDuck already at https://doc.wikimedia.org/ but something to consider in the future.