Problems with the TinyMCE plugin docs

[timhunt]

What is the URL of the page?

https://moodledev.io/docs/4.2/apis/plugintypes/tiny

What is the issue with this page?

Some issues observed while trying (and failing) to make a TinyMCE plugin during the GlobalMoot DevJam.

1. All the useful examples are hidden incollapsbile reasons, so you have to click to see them, and Find-in-page does not work.

2. https://moodledev.io/docs/4.2/apis/plugintypes/tiny#plugin-options---optionsjs-and-plugininfophp spends huge amounts of text explaining how to to pass one string value from PHP to JS - is it really that complicated? Anyway, there is no information about why you might want to do this, when it is appropriate.

3. No-where explains where is the right place to put in a capability check for a feature that should only be available to some users.

4. The page says how to add a button, and how to add a menu item. However, there is no discussion of how to choose which of those you should use.

5. https://moodledev.io/docs/4.2/apis/plugintypes/tiny#key-files - well it starte with common.js, which is hardly key, just a recommended refactoring. Why not, in The directory layout for the tiny_example plugin, and a one-line comment for what each file is.

6. I am not sure a tutorial on plguinskel is the thing to put first. It just gets in the way until you know things like whether you want a button or a menu item. I would put that at the end, with a forward-reference.

7. While we are at it, the PHPdoc comments in the code are not great. E.g. the comments on lib/editor/tiny/classes/plugin.php are like a parody of what https://moodledev.io/general/development/abc/comments says you should not to.

Are you able to provide a patch for this?

No (Default)

[timhunt]

8. Editor configuration - configuration.js - I don't know what that first technicality about Promises is about. Once you get past that, it is confusing that the two examples are not consistent. The first one uses addToolbarButtons and the second getToolbarConfiguration, which is it?

9. Looking at real examples in the code, I find it very unhelpful that the code is atomised into 8 different JS files each with a tiny fragement of code.

10. Is it the case that you should not even try to look at the Moodle docs until you fully understand TinyMCE in isolation? If so, why not say that, with a link to the relevant docs. If not, the I don't know.

[timhunt]

11. It would be good to have some convention in these docs, for when things you mention are part of the core TinyMCE API, vs things that are functions you define in your plugin.