From 4ec69dc64aca3798b5912892c07ff6ad64977c7a Mon Sep 17 00:00:00 2001
From: Artur Arseniev <artur.catch@hotmail.it>
Date: Thu, 12 Aug 2021 15:59:05 +0200
Subject: [PATCH] Update device docs

---
 docs/api.js                        |  6 ++++--
 docs/api/device.md                 | 16 ++++++++++++++-
 docs/api/device_manager.md         | 32 +++++++++++++++++-------------
 src/device_manager/model/Device.js | 17 ++++++++--------
 4 files changed, 45 insertions(+), 26 deletions(-)

diff --git a/docs/api.js b/docs/api.js
index 0db8a3875..14e03bbda 100644
--- a/docs/api.js
+++ b/docs/api.js
@@ -36,9 +36,11 @@ async function generateDocs () {
     ['parser/index.js', 'parser.md'],
   ].map(async (file) =>
     documentation.build([`${srcRoot}/${file[0]}`], { shallow: true })
-      .then(documentation.formats.md)
+      .then(cm => documentation.formats.md(cm, /*{ markdownToc: true }*/))
       .then(output => {
-        const res = output.replace(/\*\*\\\[/g, '**[');
+        const res = output
+          .replace(/\*\*\\\[/g, '**[')
+          .replace('**Extends Model**', '');
         fs.writeFileSync(`${docRoot}/api/${file[1]}`, res);
         log('Created', file[1]);
       })
diff --git a/docs/api/device.md b/docs/api/device.md
index 31e4b02bf..8c8782964 100644
--- a/docs/api/device.md
+++ b/docs/api/device.md
@@ -1,9 +1,23 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-## getWidth
+## Device
+
+
+
+### Properties
+
+*   `name` **[String][1]?** Device type, eg. `Mobile`
+*   `width` **[String][1]?** Width to set for the editor iframe, eg. '900px'
+*   `height` **[String][1]?** Height to set for the editor iframe, eg. '600px'
+*   `widthMedia` **[String][1]?** The width which will be used in media queries, If empty the width will be used
+*   `priority` **[Number][2]?** Setup the order of media queries
+
+### getWidth
 
 Get device width.
 
 Returns **[String][1]** 
 
 [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
diff --git a/docs/api/device_manager.md b/docs/api/device_manager.md
index 7d6718df0..1c6aa10ed 100644
--- a/docs/api/device_manager.md
+++ b/docs/api/device_manager.md
@@ -36,24 +36,28 @@ const deviceManager = editor.Devices;
 
 ## add
 
-Add new device.
+Add new device
 
 ### Parameters
 
-*   `id` **[String][5]** Device id
-*   `width` **[String][5]** Width of the device
-*   `options` **[Object][6]?** Custom options (optional, default `{}`)
+*   `props` **[Object][5]** Device properties
+*   `options`   (optional, default `{}`)
 
 ### Examples
 
 ```javascript
-deviceManager.add('tablet', '900px');
-deviceManager.add('tablet2', '900px', {
- height: '300px',
- // At first, GrapesJS tries to localize the name by device id.
- // In case is not found, the `name` property is used (or `id` if name is missing)
+const device1 = deviceManager.add({
+ // Without an explicit ID, the `name` will be taken. In case of missing `name`, a random ID will be created.
+ id: 'tablet',
+ name: 'Tablet',
+ width: '900px', // This width will be applied on the canvas frame and for the CSS media
+});
+const device2 = deviceManager.add({
+ id: 'tablet2',
  name: 'Tablet 2',
- widthMedia: '810px', // the width that will be used for the CSS media
+ width: '800px', // This width will be applied on the canvas frame
+ widthMedia: '810px', // This width that will be used for the CSS media
+ height: '600px', // Height will be applied on the canvas frame
 });
 ```
 
@@ -61,11 +65,11 @@ Returns **[Device]** Added device
 
 ## get
 
-Return device by name.
+Return device by name
 
 ### Parameters
 
-*   `name` **[String][5]** Name of the device
+*   `name` **[String][6]** Name of the device
 
 ### Examples
 
@@ -99,6 +103,6 @@ Returns **Collection**
 
 [4]: #getAll
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
diff --git a/src/device_manager/model/Device.js b/src/device_manager/model/Device.js
index b9e5519fb..921ff23b1 100644
--- a/src/device_manager/model/Device.js
+++ b/src/device_manager/model/Device.js
@@ -1,21 +1,20 @@
 import { Model } from 'backbone';
 
+/**
+ * @typedef Component
+ * @property {String} [name=''] Device type, eg. `Mobile`
+ * @property {String} [width] Width to set for the editor iframe, eg. '900px'
+ * @property {String} [height=''] Height to set for the editor iframe, eg. '600px'
+ * @property {String} [widthMedia=''] The width which will be used in media queries, If empty the width will be used
+ * @property {Number} [priority=null] Setup the order of media queries
+ */
 export default class Device extends Model {
   defaults() {
     return {
       name: '',
-
-      // Width to set for the editor iframe
       width: null,
-
-      // Height to set for the editor iframe
       height: '',
-
-      // The width which will be used in media queries,
-      // If empty the width will be used
       widthMedia: null,
-
-      // Setup the order of media queries
       priority: null
     };
   }