For example, somewhere on https://www.mediawiki.org/wiki/OOUI/Widgets/Buttons_and_Switches it should list the methods available for buttons, such as setIcon(), setLabel(), setFlags(), setTarget(), setHref(), setNoFollow(), etc., and explain what they do. Otherwise, you have to dig through OO.ui.ButtonWidget, it's parent constructor, and its 7 mix-in constructors.
Description
Description
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Open | None | T155473 Improve documentation of OOUI | |||
| Open | None | T95060 Documentation for OOUI widgets needs to list what methods are available for each widget |
Event Timeline
Comment Actions
@kaldari, have you looked at the generated jsduck documentation at https://doc.wikimedia.org/oojs-ui/master/#!/api/OO.ui.ButtonWidget ? That seems to include all the mixins methods.
@KMenger, have you thought about how best to combine written wiki documentation with the generated documentation? It's a hard problem! If there are tools that would help, e.g. T91626: Technology to transclude git content into wiki pages, let's talk.
Comment Actions
Hi S,
Thanks for pointing me toward the discussion about this. Many things to think about, indeed!
In terms of OOjs UI, yes, the methods/configs are all documented in jsduck. The MediaWiki doc was intended to be more of an overview/introduction that would help people more easily discover what was in the library. I did link to the code-gen docs from each class with a note that a complete list of methods/configs could be found there (and I also linked back to the wiki from the code-gen docs, for things like more context/examples/etc). The plan was that the two publications could complement each other. If it is important that the methods be documented in the wiki page as well as jsduck, yes, my feeling is that would best be done with a system that pulls that content in from the code (there is much redundancy and I think it would be a pain to maintain otherwise).
My feeling is that linking back and forth between the two documents (jsduck and MediaWiki) is not unreasonable and that adding the method descriptions to the MediaWiki page is a bit counter to the original intent of the document, but if it is useful to have the method/config docs there, perhaps those descriptions could be pulled into some sort of closed div that users could open if they wanted to, and which wouldn't add quite so much bulk to the pages (there are often quite a lot of methods/configs and I fear that it would make the document harder to scan/scroll if simply pulled in and displayed).
In terms of other places/ways in which we could repurpose OOjs UI content between different platforms, the only other thing that comes to mind at the moment is the example code, which is often very similar in both docs. I stripped out a lot of the comments for the jsduck version (which has a live preview!), so that would be lost (or added) were these assets to be shared between the two documents and maintained in one place, but it might make sense, depending on how difficult it is to do. Some of the high-level class description is similar as well--in some cases identical, but not always.