Page MenuHomePhabricator

Documentation for OOUI widgets needs to list what methods are available for each widget
Open, LowPublic

Description

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.

Event Timeline

kaldari raised the priority of this task from to Needs Triage.
kaldari updated the task description. (Show Details)
kaldari added projects: OOUI, Documentation.
kaldari added a subscriber: kaldari.

@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.

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.

Jdforrester-WMF set Security to None.
Volker_E renamed this task from Documentation for OOjs UI widgets needs to list what methods are available for each widget to Documentation for OOUI widgets needs to list what methods are available for each widget.Jan 17 2018, 12:51 AM
Volker_E updated the task description. (Show Details)