Improve the custom component and custom plugin documentation

[S-U-M-1]

I'm trying to develop a simple button plugin for TinyMCE 4.9.6, in Wordpress 5.4.1, and I've never seen such bad API documentation in my life.

Take addButton for example.

settings (Object) - Settings object with title, cmd etc.

'etc.'? Seriously?

Apparently, it is referring to the settings listed here (thanks to this Stack Overflow answer). But it has no link to this page, and no indication that it would be here.

There is a slightly more helpful "archive" version of the TinyMCE 4 API documentation, featuring pages like this for the tinymce.Editor.submit event. That page has a helpful example and information showing the arguments that the function inside it takes. However, almost all of the archive version's links redirect to the worse current version.

As soon as we go to the current documentation, there is almost nothing. No example, no information on arguments. In fact, in order to find anything on function arguments, I had to go to tinymce.WindowManager#open and then to this page on dialogues. There was absolutely no information on the submit event in tinymce.Event in the modern documentation. Additionally, a submit event doesn't exist under the current tinymce.Editor.

The Algolia search also returns nothing useful for the search term "submit event". In general, I've found the search to be useless.

I'm not alone in thinking this. Several others on Stack Overflow have commented about how bad the tinyMCE API documentation is, such as here and here.

Please do something, anything about this.

• Point me to where I can find information on function arguments for each method.
• Provide a list of all settings entries for each method (or a link to the relevant object and all its entries).
• Please make the Create a Plugin page much clearer, showing an actual step-by-step highlighting all of the function arguments and settings parameters and their meanings and how to create a plugin, not just a single example of a plugin.
• Please show code examples and/or screenshots or interactive results for what each method does. Don't just have this:

[tylerkelly13]

Hi @S-U-M-1,

Atrocious API documentation

That is a fair statement about the TinyMCE 4 API documentation. You've also provided a lot of useful feedback which we can use to make the docs better.

Unfortunately, the API documentation is auto-generated from the TinyMCE source, so to update the TinyMCE 4 API documentation, we would need to release a patch version. At this time, we only release patches for security fixes on TinyMCE 4. Therefore it is unlikely that the TinyMCE 4 API documentation will be fixed. Note that TinyMCE 4 will reach end-of-support at the end of this year.

The docs have been improved for TinyMCE 5, with docs pages on Creating a plugin and Custom toolbar buttons.

We are also planning to review our API docs and we’re looking into ways to improve the docs search functionality.

[S-U-M-1]

@tylerkelly13 Thank you for your response.

As it is, it seems the official "Classic Editor" plugin for WordPress uses TinyMCE 4.9.6, so that's what I've had to develop with.

The docs have been improved for TinyMCE 5, with docs pages on Creating a plugin and Custom toolbar buttons.

Unfortunately, the Create a plugin page for TinyMCE 5 is almost exactly the same as the one for TinyMCE 4.

A lot of my criticisms also apply to the TinyMCE 5 documentation. For example, addButton and all the other methods really need some links to the corresponding object pages. At the moment, anyone arriving at this page first, trying to find how "addButton" can be programmed, will be left totally confused.

There is a lot of integration lacking in the docs, and related pages are separated across multiple disparate categories. It also doesn't help that the UI component pages, supposedly plugin-developer information, are nested between two non-plugin-developer categories, Plugins (pre-made) and Premium features. The next plugin-developer information page is in "Advanced topics", 2 sections down, and then the API Reference, all the way at the bottom.

I eventually found out some more about how to interpret the argument information, but it's laid out in an unintuitive and hard-to-find way, with a lot of navigating between different sections or pages.

[tylerkelly13]

Hi @S-U-M-1

I've updated the title of the issue to reflect the issues raised here in relation to the TinyMCE 5 documentation.

[androb]

Some valuable feedback @S-U-M-1 , thanks