Merge pull request #254 from Lange/typedefs

docs: improve consistency of array typings; introduce typedefs category

docs/comments.js

@@ -30,6 +30,14 @@ const processComments = comments => {
     let errors = [];
 
     comments.forEach(comment => {
+        if (comment.typedef) {
+            comment.comment = undefined;
+            comment.context = undefined;
+            sorted['typedefs'] = sorted['typedefs'] || [];
+            sorted['typedefs'].push(comment);
+            return;
+        }
+
         if (typeof comment.api === 'undefined') return;
         let validationFailures = validateComment(comment);
 
@@ -84,9 +92,7 @@ const validateComment = comment => {
             fullContext: Object.assign({}, comment)
         };
     }
-
+};
-    return;
-}
 
 const files = glob.sync(config.srcGlob);
 const comments = processComments(parseFiles(files));

docs/generated/comments.json

@@ -6,7 +6,7 @@
         "description": "Indicates a scene change.",
         "return": [
           "{String} `scene-name` The new scene.",
-          "{Array} `sources` List of sources in the new scene."
+          "{Array<Source>} `sources` List of sources in the new scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
         ],
         "api": "events",
         "name": "SwitchScenes",
@@ -19,9 +19,9 @@
             "description": "The new scene."
           },
           {
-            "type": "Array",
+            "type": "Array<Source>",
             "name": "sources",
-            "description": "List of sources in the new scene."
+            "description": "List of sources in the new scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
           }
         ],
         "names": [
@@ -1246,7 +1246,7 @@
         "description": "The selected preview scene has changed (only available in Studio Mode).",
         "return": [
           "{String} `scene-name` Name of the scene being previewed.",
-          "{Source|Array} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
+          "{Array<Source>} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
         ],
         "api": "events",
         "name": "PreviewSceneChanged",
@@ -1259,7 +1259,7 @@
             "description": "Name of the scene being previewed."
           },
           {
-            "type": "Source|Array",
+            "type": "Array<Source>",
             "name": "sources",
             "description": "List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene)."
           }
@@ -1702,14 +1702,14 @@
       {
         "subheads": [],
         "description": "Get a list of available profiles.",
-        "return": "{Object|Array} `profiles` List of available profiles.",
+        "return": "{Array<Object>} `profiles` List of available profiles.",
         "api": "requests",
         "name": "ListProfiles",
         "category": "profiles",
         "since": "4.0.0",
         "returns": [
           {
-            "type": "Object|Array",
+            "type": "Array<Object>",
             "name": "profiles",
             "description": "List of available profiles."
           }
@@ -2144,24 +2144,16 @@
       {
         "subheads": [],
         "description": "List available scene collections",
-        "return": [
+        "return": "{Array<String>} `scene-collections` Scene collections list",
-          "{Object|Array} `scene-collections` Scene collections list",
-          "{String} `scene-collections.*.`"
-        ],
         "api": "requests",
         "name": "ListSceneCollections",
         "category": "scene collections",
         "since": "4.0.0",
         "returns": [
           {
-            "type": "Object|Array",
+            "type": "Array<String>",
             "name": "scene-collections",
             "description": "Scene collections list"
-          },
-          {
-            "type": "String",
-            "name": "scene-collections.*.",
-            "description": ""
           }
         ],
         "names": [
@@ -2861,7 +2853,7 @@
         "description": "Get the current scene's name and source items.",
         "return": [
           "{String} `name` Name of the currently active scene.",
-          "{Source|Array} `sources` Ordered list of the current scene's source items."
+          "{Array<Source>} `sources` Ordered list of the current scene's source items."
         ],
         "api": "requests",
         "name": "GetCurrentScene",
@@ -2874,7 +2866,7 @@
             "description": "Name of the currently active scene."
           },
           {
-            "type": "Source|Array",
+            "type": "Array<Source>",
             "name": "sources",
             "description": "Ordered list of the current scene's source items."
           }
@@ -2910,7 +2902,7 @@
         "description": "Get a list of scenes in the currently active profile.",
         "return": [
           "{String} `current-scene` Name of the currently active scene.",
-          "{Scene|Array} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information)."
+          "{Array<Scene>} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information)."
         ],
         "api": "requests",
         "name": "GetSceneList",
@@ -2923,7 +2915,7 @@
             "description": "Name of the currently active scene."
           },
           {
-            "type": "Scene|Array",
+            "type": "Array<Scene>",
             "name": "scenes",
             "description": "Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information)."
           }
@@ -2960,7 +2952,7 @@
         "subheads": [],
         "description": "List all sources available in the running OBS instance",
         "return": [
-          "{Array of Objects} `sources` Array of sources as objects",
+          "{Array<Object>} `sources` Array of sources",
           "{String} `sources.*.name` Unique source name",
           "{String} `sources.*.typeId` Non-unique source internal type (a.k.a type id)",
           "{String} `sources.*.type` Source type. Value is one of the following: \"input\", \"filter\", \"transition\", \"scene\" or \"unknown\""
@@ -2971,9 +2963,9 @@
         "since": "4.3.0",
         "returns": [
           {
-            "type": "Array of Objects",
+            "type": "Array<Object>",
             "name": "sources",
-            "description": "Array of sources as objects"
+            "description": "Array of sources"
           },
           {
             "type": "String",
@@ -3021,7 +3013,7 @@
         "subheads": [],
         "description": "Get a list of all available sources types",
         "return": [
-          "{Array of Objects} `ids` Array of sources as objects",
+          "{Array<Object>} `ids` Array of source types",
           "{String} `ids.*.typeId` Non-unique internal source type ID",
           "{String} `ids.*.displayName` Display name of the source type",
           "{String} `ids.*.type` Type. Value is one of the following: \"input\", \"filter\", \"transition\" or \"other\"",
@@ -3041,9 +3033,9 @@
         "since": "4.3.0",
         "returns": [
           {
-            "type": "Array of Objects",
+            "type": "Array<Object>",
             "name": "ids",
-            "description": "Array of sources as objects"
+            "description": "Array of source types"
           },
           {
             "type": "String",
@@ -4493,7 +4485,7 @@
         "description": "List filters applied to a source",
         "param": "{String} `sourceName` Source name",
         "return": [
-          "{Array of Objects} `filters` List of filters for the specified source",
+          "{Array<Object>} `filters` List of filters for the specified source",
           "{String} `filters.*.type` Filter type",
           "{String} `filters.*.name` Filter name",
           "{Object} `filters.*.settings` Filter settings"
@@ -4504,7 +4496,7 @@
         "since": "unreleased",
         "returns": [
           {
-            "type": "Array of Objects",
+            "type": "Array<Object>",
             "name": "filters",
             "description": "List of filters for the specified source"
           },
@@ -5303,7 +5295,7 @@
         "description": "Get the name of the currently previewed scene and its list of sources.\nWill return an `error` if Studio Mode is not enabled.",
         "return": [
           "{String} `name` The name of the active preview scene.",
-          "{Source|Array} `sources`"
+          "{Array<Source>} `sources`"
         ],
         "api": "requests",
         "name": "GetPreviewScene",
@@ -5316,7 +5308,7 @@
             "description": "The name of the active preview scene."
           },
           {
-            "type": "Source|Array",
+            "type": "Array<Source>",
             "name": "sources",
             "description": ""
           }
@@ -5549,8 +5541,8 @@
         "description": "List of all transitions available in the frontend's dropdown menu.",
         "return": [
           "{String} `current-transition` Name of the currently active transition.",
-          "{Object|Array} `transitions` List of transitions.",
+          "{Array<Object>} `transitions` List of transitions.",
-          "{String} `transitions[].name` Name of the transition."
+          "{String} `transitions.*.name` Name of the transition."
         ],
         "api": "requests",
         "name": "GetTransitionList",
@@ -5563,13 +5555,13 @@
             "description": "Name of the currently active transition."
           },
           {
-            "type": "Object|Array",
+            "type": "Array<Object>",
             "name": "transitions",
             "description": "List of transitions."
           },
           {
             "type": "String",
-            "name": "transitions[].name",
+            "name": "transitions.*.name",
             "description": "Name of the transition."
           }
         ],
@@ -5772,5 +5764,121 @@
         "examples": []
       }
     ]
-  }
+  },
+  "typedefs": [
+    {
+      "subheads": [],
+      "typedef": "{Object} `Scene`",
+      "property": [
+        "{String} `name` Name of the currently active scene.",
+        "{Array<Source>} `sources` Ordered list of the current scene's source items."
+      ],
+      "properties": [
+        {
+          "type": "String",
+          "name": "name",
+          "description": "Name of the currently active scene."
+        },
+        {
+          "type": "Array<Source>",
+          "name": "sources",
+          "description": "Ordered list of the current scene's source items."
+        }
+      ],
+      "typedefs": [
+        {
+          "type": "Object",
+          "name": "Scene",
+          "description": ""
+        }
+      ],
+      "name": "",
+      "heading": {
+        "level": 2,
+        "text": ""
+      },
+      "examples": []
+    },
+    {
+      "subheads": [],
+      "typedef": "{Object} `Source` An OBS Scene Item.",
+      "property": [
+        "{Number} `cy`",
+        "{Number} `cx`",
+        "{String} `name` The name of this Scene Item.",
+        "{Boolean} `render` Whether or not this Scene Item is set to \"visible\".",
+        "{Number} `source_cx`",
+        "{Number} `source_cy`",
+        "{String} `type` Source type. Value is one of the following: \"input\", \"filter\", \"transition\", \"scene\" or \"unknown\"",
+        "{Number} `volume`",
+        "{Number} `x`",
+        "{Number} `y`"
+      ],
+      "properties": [
+        {
+          "type": "Number",
+          "name": "cy",
+          "description": ""
+        },
+        {
+          "type": "Number",
+          "name": "cx",
+          "description": ""
+        },
+        {
+          "type": "String",
+          "name": "name",
+          "description": "The name of this Scene Item."
+        },
+        {
+          "type": "Boolean",
+          "name": "render",
+          "description": "Whether or not this Scene Item is set to \"visible\"."
+        },
+        {
+          "type": "Number",
+          "name": "source_cx",
+          "description": ""
+        },
+        {
+          "type": "Number",
+          "name": "source_cy",
+          "description": ""
+        },
+        {
+          "type": "String",
+          "name": "type",
+          "description": "Source type. Value is one of the following: \"input\", \"filter\", \"transition\", \"scene\" or \"unknown\""
+        },
+        {
+          "type": "Number",
+          "name": "volume",
+          "description": ""
+        },
+        {
+          "type": "Number",
+          "name": "x",
+          "description": ""
+        },
+        {
+          "type": "Number",
+          "name": "y",
+          "description": ""
+        }
+      ],
+      "typedefs": [
+        {
+          "type": "Object",
+          "name": "Source",
+          "description": "An OBS Scene Item."
+        }
+      ],
+      "name": "",
+      "heading": {
+        "level": 2,
+        "text": ""
+      },
+      "examples": []
+    }
+  ]
 }

docs/generated/protocol.md

@@ -43,6 +43,9 @@ auth_response = base64_encode(auth_response_hash)
 
 <!-- toc -->
 
+- [Typedefs](#typedefs)
+  * [Scene](#scene)
+  * [Source](#source)
 - [Events](#events)
   * [Scenes](#scenes)
     + [SwitchScenes](#switchscenes)
@@ -174,6 +177,31 @@ auth_response = base64_encode(auth_response_hash)
 
 <!-- tocstop -->
 
+# Typedefs
+These are complex types, such as `Source` and `Scene`, which are used as arguments or return values in multiple requests and/or events. 
+
+
+## Scene
+| Name | Type  | Description |
+| ---- | :---: | ------------|
+| `name` | _String_ | Name of the currently active scene. |
+| `sources` | _Array&lt;Source&gt;_ | Ordered list of the current scene's source items. |
+## Source
+| Name | Type  | Description |
+| ---- | :---: | ------------|
+| `cy` | _Number_ |  |
+| `cx` | _Number_ |  |
+| `name` | _String_ | The name of this Scene Item. |
+| `render` | _Boolean_ | Whether or not this Scene Item is set to "visible". |
+| `source_cx` | _Number_ |  |
+| `source_cy` | _Number_ |  |
+| `type` | _String_ | Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown" |
+| `volume` | _Number_ |  |
+| `x` | _Number_ |  |
+| `y` | _Number_ |  |
+
+
+
 # Events
 Events are broadcast by the server to each connected client when a recognized action occurs within OBS.
 
@@ -201,7 +229,7 @@ Indicates a scene change.
 | Name | Type  | Description |
 | ---- | :---: | ------------|
 | `scene-name` | _String_ | The new scene. |
-| `sources` | _Array_ | List of sources in the new scene. |
+| `sources` | _Array&lt;Source&gt;_ | List of sources in the new scene. Same specification as [`GetCurrentScene`](#getcurrentscene). |
 
 
 ---
@@ -661,7 +689,7 @@ The selected preview scene has changed (only available in Studio Mode).
 | Name | Type  | Description |
 | ---- | :---: | ------------|
 | `scene-name` | _String_ | Name of the scene being previewed. |
-| `sources` | _Source\|Array_ | List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene). |
+| `sources` | _Array&lt;Source&gt;_ | List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene). |
 
 
 ---
@@ -883,7 +911,7 @@ _No specified parameters._
 
 | Name | Type  | Description |
 | ---- | :---: | ------------|
-| `profiles` | _Object\|Array_ | List of available profiles. |
+| `profiles` | _Array&lt;Object&gt;_ | List of available profiles. |
 
 
 ---
@@ -1117,8 +1145,7 @@ _No specified parameters._
 
 | Name | Type  | Description |
 | ---- | :---: | ------------|
-| `scene-collections` | _Object\|Array_ | Scene collections list |
+| `scene-collections` | _Array&lt;String&gt;_ | Scene collections list |
-| `scene-collections.*.` | _String_ |  |
 
 
 ---
@@ -1357,7 +1384,7 @@ _No specified parameters._
 | Name | Type  | Description |
 | ---- | :---: | ------------|
 | `name` | _String_ | Name of the currently active scene. |
-| `sources` | _Source\|Array_ | Ordered list of the current scene's source items. |
+| `sources` | _Array&lt;Source&gt;_ | Ordered list of the current scene's source items. |
 
 
 ---
@@ -1378,7 +1405,7 @@ _No specified parameters._
 | Name | Type  | Description |
 | ---- | :---: | ------------|
 | `current-scene` | _String_ | Name of the currently active scene. |
-| `scenes` | _Scene\|Array_ | Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information). |
+| `scenes` | _Array&lt;Scene&gt;_ | Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information). |
 
 
 ---
@@ -1400,7 +1427,7 @@ _No specified parameters._
 
 | Name | Type  | Description |
 | ---- | :---: | ------------|
-| `sources` | _Array of Objects_ | Array of sources as objects |
+| `sources` | _Array&lt;Object&gt;_ | Array of sources |
 | `sources.*.name` | _String_ | Unique source name |
 | `sources.*.typeId` | _String_ | Non-unique source internal type (a.k.a type id) |
 | `sources.*.type` | _String_ | Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown" |
@@ -1423,7 +1450,7 @@ _No specified parameters._
 
 | Name | Type  | Description |
 | ---- | :---: | ------------|
-| `ids` | _Array of Objects_ | Array of sources as objects |
+| `ids` | _Array&lt;Object&gt;_ | Array of source types |
 | `ids.*.typeId` | _String_ | Non-unique internal source type ID |
 | `ids.*.displayName` | _String_ | Display name of the source type |
 | `ids.*.type` | _String_ | Type. Value is one of the following: "input", "filter", "transition" or "other" |
@@ -1900,7 +1927,7 @@ List filters applied to a source
 
 | Name | Type  | Description |
 | ---- | :---: | ------------|
-| `filters` | _Array of Objects_ | List of filters for the specified source |
+| `filters` | _Array&lt;Object&gt;_ | List of filters for the specified source |
 | `filters.*.type` | _String_ | Filter type |
 | `filters.*.name` | _String_ | Filter name |
 | `filters.*.settings` | _Object_ | Filter settings |
@@ -2217,7 +2244,7 @@ _No specified parameters._
 | Name | Type  | Description |
 | ---- | :---: | ------------|
 | `name` | _String_ | The name of the active preview scene. |
-| `sources` | _Source\|Array_ |  |
+| `sources` | _Array&lt;Source&gt;_ |  |
 
 
 ---
@@ -2335,8 +2362,8 @@ _No specified parameters._
 | Name | Type  | Description |
 | ---- | :---: | ------------|
 | `current-transition` | _String_ | Name of the currently active transition. |
-| `transitions` | _Object\|Array_ | List of transitions. |
+| `transitions` | _Array&lt;Object&gt;_ | List of transitions. |
-| `transitions[].name` | _String_ | Name of the transition. |
+| `transitions.*.name` | _String_ | Name of the transition. |
 
 
 ---

docs/partials/typedefsHeader.md

@@ -0,0 +1,2 @@
+# Typedefs
+These are complex types, such as `Source` and `Scene`, which are used as arguments or return values in multiple requests and/or events. 

docs/protocol.hbs

@@ -7,6 +7,19 @@
 
 
 
+{{#read "partials/typedefsHeader.md"}}{{/read}}
+
+{{#each typedefs}}
+## {{typedefs.0.name}}
+| Name | Type  | Description |
+| ---- | :---: | ------------|
+{{#each properties}}
+| `{{name}}` | _{{depipe type}}_ | {{{depipe description}}} |
+{{/each}}
+{{/each}}
+
+
+
 {{#read "partials/eventsHeader.md"}}{{/read}}
 
 {{#each events}}

src/WSEvents.cpp

@@ -292,7 +292,7 @@ const char* WSEvents::GetRecordingTimecode() {
  * Indicates a scene change.
  *
  * @return {String} `scene-name` The new scene.
- * @return {Array} `sources` List of sources in the new scene.
+ * @return {Array<Source>} `sources` List of sources in the new scene. Same specification as [`GetCurrentScene`](#getcurrentscene).
  *
  * @api events
  * @name SwitchScenes
@@ -907,7 +907,7 @@ void WSEvents::OnSceneItemVisibilityChanged(void* param, calldata_t* data) {
  * The selected preview scene has changed (only available in Studio Mode).
  *
  * @return {String} `scene-name` Name of the scene being previewed.
- * @return {Source|Array} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene).
+ * @return {Array<Source>} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene).
  *
  * @api events
  * @name PreviewSceneChanged

src/WSRequestHandler_Profiles.cpp

@@ -50,7 +50,7 @@ void WSRequestHandler::HandleGetCurrentProfile(WSRequestHandler* req) {
 /**
  * Get a list of available profiles.
  *
- * @return {Object|Array} `profiles` List of available profiles.
+ * @return {Array<Object>} `profiles` List of available profiles.
  *
  * @api requests
  * @name ListProfiles

src/WSRequestHandler_SceneCollections.cpp

@@ -50,8 +50,7 @@ void WSRequestHandler::HandleGetCurrentSceneCollection(WSRequestHandler* req) {
 /**
  * List available scene collections
  *
- * @return {Object|Array} `scene-collections` Scene collections list
+ * @return {Array<String>} `scene-collections` Scene collections list
- * @return {String} `scene-collections.*.`
  *
  * @api requests
  * @name ListSceneCollections

src/WSRequestHandler_Scenes.cpp

@@ -3,6 +3,12 @@
 
 #include "WSRequestHandler.h"
 
+/**
+* @typedef {Object} `Scene`
+* @property {String} `name` Name of the currently active scene.
+* @property {Array<Source>} `sources` Ordered list of the current scene's source items.
+*/
+
 /**
  * Switch to the specified scene.
  *
@@ -34,7 +40,7 @@
  * Get the current scene's name and source items.
  * 
  * @return {String} `name` Name of the currently active scene.
- * @return {Source|Array} `sources` Ordered list of the current scene's source items.
+ * @return {Array<Source>} `sources` Ordered list of the current scene's source items.
  *
  * @api requests
  * @name GetCurrentScene
@@ -56,7 +62,7 @@ void WSRequestHandler::HandleGetCurrentScene(WSRequestHandler* req) {
  * Get a list of scenes in the currently active profile.
  * 
  * @return {String} `current-scene` Name of the currently active scene.
- * @return {Scene|Array} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information).
+ * @return {Array<Scene>} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information).
  *
  * @api requests
  * @name GetSceneList

src/WSRequestHandler_Sources.cpp

@@ -3,10 +3,24 @@
 
 #include "WSRequestHandler.h"
 
+/**
+* @typedef {Object} `Source` An OBS Scene Item.
+* @property {Number} `cy`
+* @property {Number} `cx`
+* @property {String} `name` The name of this Scene Item.
+* @property {Boolean} `render` Whether or not this Scene Item is set to "visible".
+* @property {Number} `source_cx`
+* @property {Number} `source_cy`
+* @property {String} `type` Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown"
+* @property {Number} `volume`
+* @property {Number} `x`
+* @property {Number} `y`
+*/
+
 /**
 * List all sources available in the running OBS instance
 *
-* @return {Array of Objects} `sources` Array of sources as objects
+* @return {Array<Object>} `sources` Array of sources
 * @return {String} `sources.*.name` Unique source name
 * @return {String} `sources.*.typeId` Non-unique source internal type (a.k.a type id)
 * @return {String} `sources.*.type` Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown"
@@ -64,7 +78,7 @@ void WSRequestHandler::HandleGetSourcesList(WSRequestHandler* req) {
 /**
 * Get a list of all available sources types
 *
-* @return {Array of Objects} `ids` Array of sources as objects
+* @return {Array<Object>} `ids` Array of source types
 * @return {String} `ids.*.typeId` Non-unique internal source type ID
 * @return {String} `ids.*.displayName` Display name of the source type
 * @return {String} `ids.*.type` Type. Value is one of the following: "input", "filter", "transition" or "other"
@@ -1119,7 +1133,7 @@ void WSRequestHandler::HandleDuplicateSceneItem(WSRequestHandler* req) {
 *
 * @param {String} `sourceName` Source name
 *
-* @return {Array of Objects} `filters` List of filters for the specified source
+* @return {Array<Object>} `filters` List of filters for the specified source
 * @return {String} `filters.*.type` Filter type
 * @return {String} `filters.*.name` Filter name
 * @return {Object} `filters.*.settings` Filter settings

src/WSRequestHandler_StudioMode.cpp

@@ -27,7 +27,7 @@
  * Will return an `error` if Studio Mode is not enabled.
  *
  * @return {String} `name` The name of the active preview scene.
- * @return {Source|Array} `sources`
+ * @return {Array<Source>} `sources`
  *
  * @api requests
  * @name GetPreviewScene

src/WSRequestHandler_Transitions.cpp

@@ -7,8 +7,8 @@
  * List of all transitions available in the frontend's dropdown menu.
  *
  * @return {String} `current-transition` Name of the currently active transition.
- * @return {Object|Array} `transitions` List of transitions.
+ * @return {Array<Object>} `transitions` List of transitions.
- * @return {String} `transitions[].name` Name of the transition.
+ * @return {String} `transitions.*.name` Name of the transition.
  *
  * @api requests
  * @name GetTransitionList