Document the button hooks

CHANGES.md

@@ -6,6 +6,8 @@
 - #2275: Allow punctuation to immediately precede a mention
 - Bugfix: Connection protocol not updated based on XEP-0156 connection methods
 - Bugfix: `null` inserted by emoji picker and can't switch between skintones
+- New hook: [getMessageActionButtons](https://conversejs.org/docs/html/api/-_converse.html#event:getMessageActionButtons)
+- File structure reordering: All plugins are now in `./plugins` folders.
 - New configuration setting: [show_tab_notifications](https://conversejs.org/docs/html/configuration.html#show-tab-notifications)
 
 ### Breaking Changes

src/components/message-actions.js

@@ -70,16 +70,16 @@ class MessageActions extends CustomElement {
          * *Hook* which allows plugins to add more message action buttons
          * @event _converse#getMessageActionButtons
          * @example
-            api.listen.on('getMessageActionButtons', (el, buttons) => {
-                buttons.push({
-                    'i18n_text': 'Foo',
-                    'handler': ev => alert('Foo!'),
-                    'button_class': 'chat-msg__action-foo',
-                    'icon_class': 'fa fa-check',
-                    'name': 'foo'
-                });
-                return buttons;
-            });
+         *  api.listen.on('getMessageActionButtons', (el, buttons) => {
+         *      buttons.push({
+         *          'i18n_text': 'Foo',
+         *          'handler': ev => alert('Foo!'),
+         *          'button_class': 'chat-msg__action-foo',
+         *          'icon_class': 'fa fa-check',
+         *          'name': 'foo'
+         *      });
+         *      return buttons;
+         *  });
          */
         return api.hook('getMessageActionButtons', this, buttons);
     }

src/components/toolbar.js

@@ -79,6 +79,13 @@ export class ChatToolbar extends CustomElement {
         /**
          * *Hook* which allows plugins to add more buttons to a chat's toolbar
          * @event _converse#getToolbarButtons
+         * @example
+         *  api.listen.on('getToolbarButtons', (toolbar_el, buttons) {
+         *      buttons.push(html`
+         *          <button @click=${() => alert('Foo!')}>Foo</button>`
+         *      );
+         *      return buttons;
+         *  }
          */
         return _converse.api.hook('getToolbarButtons', this, buttons);
     }

src/plugins/chatview.js

@@ -333,6 +333,18 @@ export const ChatBoxView = View.extend({
         /**
          * *Hook* which allows plugins to add more buttons to a chat's heading.
          * @event _converse#getHeadingButtons
+         * @example
+         *  api.listen.on('getHeadingButtons', (view, buttons) => {
+         *      buttons.push({
+         *          'i18n_title': __('Foo'),
+         *          'i18n_text': __('Foo Bar'),
+         *          'handler': ev => alert('Foo!'),
+         *          'a_class': 'toggle-foo',
+         *          'icon_class': 'fa-foo',
+         *          'name': 'foo'
+         *      });
+         *      return buttons;
+         *  });
          */
         return _converse.api.hook('getHeadingButtons', this, buttons);
     },

src/plugins/modal.js

@@ -29,10 +29,10 @@ const modal_api = {
          * Will create a new instance of that class if an existing one isn't
          * found.
          * @param { Class } ModalClass
-         * @param { [Object] } properties - Optional properties that will be
+         * @param { Object } [properties] - Optional properties that will be
          *  set on a newly created modal instance (if no pre-existing modal was
          *  found).
-         * @param { [Event] } event - The DOM event that causes the modal to be shown.
+         * @param { Event } [event] - The DOM event that causes the modal to be shown.
          */
         show (ModalClass, properties, ev) {
             const modal = this.get(ModalClass.id) || this.create(ModalClass, properties);
@@ -51,7 +51,7 @@ const modal_api = {
         /**
          * Create a modal of the passed-in type.
          * @param { Class } ModalClass
-         * @param { [Object] } properties - Optional properties that will be
+         * @param { Object } [properties] - Optional properties that will be
          *  set on the modal instance.
          */
         create (ModalClass, properties) {