Update canvas events documentation

docs/api.js

@@ -4,9 +4,35 @@ const documentation = require('documentation');
 const fs = require('fs');
 const docRoot = __dirname;
 const srcRoot = path.join(docRoot, '../src/');
+const START_EVENTS = '{START_EVENTS}';
+const END_EVENTS = '{END_EVENTS}';
+const REPLACE_EVENTS = '{REPLACE_EVENTS}';
 
 const log = (...args) => console.log(...args);
 
+const getEventsMdFromTypes = async (filePath) => {
+  const dirname = filePath.replace(path.basename(filePath), '');
+  const typesFilePath = `${dirname}types.ts`;
+
+  if (fs.existsSync(typesFilePath) && typesFilePath.includes('canvas')) {
+    const resTypes = await documentation.build([typesFilePath], { shallow: true })
+      .then(cm => documentation.formats.md(cm, /*{ markdownToc: true }*/));
+    const indexFrom = resTypes.indexOf(START_EVENTS) + START_EVENTS.length;
+    const indexTo = resTypes.indexOf(END_EVENTS);
+
+    const result = resTypes.substring(indexFrom, indexTo)
+      .replace(/\n### Examples\n/gi, '')
+      .replace(/## /gi, '* ')
+      .replace(/\\`/gi, '`')
+      .replace(/##/gi, '')
+      .trim();
+
+    return result
+  }
+
+  return '';
+}
+
 async function generateDocs () {
   log('Start API Reference generation...');
 
@@ -56,8 +82,8 @@ async function generateDocs () {
 
     return documentation.build([filePath], { shallow: true })
       .then(cm => documentation.formats.md(cm, /*{ markdownToc: true }*/))
-      .then(output => {
-        const res = output
+      .then(async (output) => {
+        let result = output
           .replace(/\*\*\\\[/g, '**[')
           .replace(/\*\*\(\\\[/g, '**([')
           .replace(/<\\\[/g, '<[')
@@ -67,7 +93,14 @@ async function generateDocs () {
           .replace(/docsjs\./g, '')
           .replace('**Extends ModuleModel**', '')
           .replace('**Extends Model**', '');
-        fs.writeFileSync(`${docRoot}/api/${file[1]}`, res);
+
+        // Search for module event documentation
+        if (result.indexOf(REPLACE_EVENTS) >= 0) {
+          const eventsMd = await getEventsMdFromTypes(filePath);
+          result = eventsMd ? result.replace(REPLACE_EVENTS, `## Available Events\n${eventsMd}`) : result;
+        }
+
+        fs.writeFileSync(`${docRoot}/api/${file[1]}`, result);
         log('Created', file[1]);
       });
   }));

docs/api/canvas.md

@@ -24,14 +24,80 @@ canvas.setCoords(...);
 ```
 
 ## Available Events
+* `canvas:dragenter` Something is dragged inside the canvas, `DataTransfer` instance passed as an argument.
 
-*   `canvas:dragenter` - When something is dragged inside the canvas, `DataTransfer` instance passed as an argument
-*   `canvas:dragover` - When something is dragging on canvas, `DataTransfer` instance passed as an argument
-*   `canvas:drop` - Something is dropped in canvas, `DataTransfer` instance and the dropped model are passed as arguments
-*   `canvas:dragend` - When a drag operation is ended, `DataTransfer` instance passed as an argument
-*   `canvas:dragdata` - On any dataTransfer parse, `DataTransfer` instance and the `result` are passed as arguments.
+* `canvas:dragover` Something is dragging on the canvas, `DataTransfer` instance passed as an argument.
 
-By changing `result.content` you're able to customize what is dropped
+* `canvas:dragend` When a drag operation is ended, `DataTransfer` instance passed as an argument.
+
+* `canvas:dragdata` On any dataTransfer parse, `DataTransfer` instance and the `result` are passed as arguments.
By changing `result.content` you're able to customize what is dropped.
+
+* `canvas:drop` Something is dropped in canvas, `DataTransfer` instance and the dropped model are passed as arguments.
+
+* `canvas:spot` Spots updated.
+
+```javascript
+editor.on('canvas:spot', () => {
+ console.log('Spots', editor.Canvas.getSpots());
+});
+```
+
+* `canvas:spot:add` New canvas spot added.
+
+```javascript
+editor.on('canvas:spot:add', ({ spot }) => {
+ console.log('Spot added', spot);
+});
+```
+
+* `canvas:spot:update` Canvas spot updated.
+
+```javascript
+editor.on('canvas:spot:update', ({ spot }) => {
+ console.log('Spot updated', spot);
+});
+```
+
+* `canvas:spot:remove` Canvas spot removed.
+
+```javascript
+editor.on('canvas:spot:remove', ({ spot }) => {
+ console.log('Spot removed', spot);
+});
+```
+
+* `canvas:viewport` Canvas viewport updated (eg. zoom or coordinates).
+
+```javascript
+editor.on('canvas:viewport', () => {
+ const { Canvas } = editor;
+ console.log('Canvas, zoom:', Canvas.getZoom(), 'coords:', Canvas.getCoords());
+});
+```
+
+* `canvas:viewport:start` Canvas viewport update started (eg. zooming or panning)
+
+```javascript
+editor.on('canvas:viewport:start', () => {
+ console.log('viewport update started')
+});
+```
+
+* `canvas:viewport:end` Canvas viewport update ended. This event is debounced on 300ms from the `canvas:viewport:start`.
+
+```javascript
+editor.on('canvas:viewport:end', () => {
+ console.log('viewport updated ended')
+});
+```
+
+* `canvas:zoom` Canvas zoom updated.
+
+```javascript
+editor.on('canvas:zoom', () => {
+ console.log('New canvas zoom:', editor.Canvas.getZoom());
+});
+```
 
 ## Methods
 

src/canvas/index.ts

@@ -18,13 +18,8 @@
  * const canvas = editor.Canvas;
  * canvas.setCoords(...);
  * ```
- * ## Available Events
- * * `canvas:dragenter` - When something is dragged inside the canvas, `DataTransfer` instance passed as an argument
- * * `canvas:dragover` - When something is dragging on canvas, `DataTransfer` instance passed as an argument
- * * `canvas:drop` - Something is dropped in canvas, `DataTransfer` instance and the dropped model are passed as arguments
- * * `canvas:dragend` - When a drag operation is ended, `DataTransfer` instance passed as an argument
- * * `canvas:dragdata` - On any dataTransfer parse, `DataTransfer` instance and the `result` are passed as arguments.
- *  By changing `result.content` you're able to customize what is dropped
+ *
+ * {REPLACE_EVENTS}
  *
  * ## Methods
  * * [getConfig](#getconfig)

src/canvas/types.ts

@@ -1,59 +1,69 @@
+/**{START_EVENTS}*/
 export enum CanvasEvents {
   /**
-   *  Something is dragged inside the canvas, `DataTransfer` instance passed as an argument.
+   * @event `canvas:dragenter` Something is dragged inside the canvas, `DataTransfer` instance passed as an argument.
    */
   dragEnter = 'canvas:dragenter',
+
   /**
-   * Something is dragging on the canvas, `DataTransfer` instance passed as an argument.
+   * @event `canvas:dragover` Something is dragging on the canvas, `DataTransfer` instance passed as an argument.
    */
   dragOver = 'canvas:dragover',
+
   /**
-   * When a drag operation is ended, `DataTransfer` instance passed as an argument.
+   * @event `canvas:dragend` When a drag operation is ended, `DataTransfer` instance passed as an argument.
    */
   dragEnd = 'canvas:dragend',
+
   /**
-   * On any dataTransfer parse, `DataTransfer` instance and the `result` are passed as arguments.
+   * @event `canvas:dragdata` On any dataTransfer parse, `DataTransfer` instance and the `result` are passed as arguments.
    * By changing `result.content` you're able to customize what is dropped.
    */
   dragData = 'canvas:dragdata',
+
   /**
-   * Something is dropped in canvas, `DataTransfer` instance and the dropped model are passed as arguments.
+   * @event `canvas:drop` Something is dropped in canvas, `DataTransfer` instance and the dropped model are passed as arguments.
    */
   drop = 'canvas:drop',
+
   /**
-   * Spots updated.
+   * @event `canvas:spot` Spots updated.
    * @example
    * editor.on('canvas:spot', () => {
    *  console.log('Spots', editor.Canvas.getSpots());
    * });
    */
   spot = 'canvas:spot',
+
   /**
-   * New canvas spot added.
+   * @event `canvas:spot:add` New canvas spot added.
    * @example
    * editor.on('canvas:spot:add', ({ spot }) => {
    *  console.log('Spot added', spot);
    * });
    */
   spotAdd = 'canvas:spot:add',
+
   /**
-   * Canvas spot updated.
+   * @event `canvas:spot:update` Canvas spot updated.
    * @example
    * editor.on('canvas:spot:update', ({ spot }) => {
    *  console.log('Spot updated', spot);
    * });
    */
   spotUpdate = 'canvas:spot:update',
+
   /**
-   * Canvas spot removed.
+   * @event `canvas:spot:remove` Canvas spot removed.
    * @example
    * editor.on('canvas:spot:remove', ({ spot }) => {
    *  console.log('Spot removed', spot);
    * });
    */
   spotRemove = 'canvas:spot:remove',
+
   /**
-   * Canvas viewport updated (eg. zoom or coordinates).
+   * @event `canvas:viewport` Canvas viewport updated (eg. zoom or coordinates).
    * @example
    * editor.on('canvas:viewport', () => {
    *  const { Canvas } = editor;
@@ -61,25 +71,27 @@ export enum CanvasEvents {
    * });
    */
   viewport = 'canvas:viewport',
+
   /**
-   * Canvas viewport update started (eg. zooming or panning)
+   * @event `canvas:viewport:start` Canvas viewport update started (eg. zooming or panning)
    * @example
    * editor.on('canvas:viewport:start', () => {
    *  console.log('viewport update started')
    * });
    */
   viewportStart = 'canvas:viewport:start',
+
   /**
-   * Canvas viewport update ended.
-   * This event is debounced on 300ms from the `canvas:viewport:start`.
+   * @event `canvas:viewport:end` Canvas viewport update ended. This event is debounced on 300ms from the `canvas:viewport:start`.
    * @example
    * editor.on('canvas:viewport:end', () => {
    *  console.log('viewport updated ended')
    * });
    */
   viewportEnd = 'canvas:viewport:end',
+
   /**
-   * Canvas zoom updated.
+   * @event `canvas:zoom` Canvas zoom updated.
    * @example
    * editor.on('canvas:zoom', () => {
    *  console.log('New canvas zoom:', editor.Canvas.getZoom());
@@ -87,3 +99,4 @@ export enum CanvasEvents {
    */
   zoom = 'canvas:zoom',
 }
+/**{END_EVENTS}*/