Problems with the TinyMCE plugin docs

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)

Review the TinyMCE plugin page at moodledev.io/docs/4.2/apis/plugintypes/tiny, including its plugin-options and key-files sections, then inspect the tiny_example layout and lib/editor/tiny/classes/plugin.php comments. Restructure the guidance so examples are searchable, explain option passing and capability checks, clarify button versus menu-item choices, and improve the PHPdoc comments; done means all seven reported concerns are addressed.