diff --git a/docs/comments.js b/docs/comments.js index 46a00fc2..c396c5da 100644 --- a/docs/comments.js +++ b/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)); diff --git a/docs/generated/comments.json b/docs/generated/comments.json index 3a3f98e2..6695b0b5 100644 --- a/docs/generated/comments.json +++ b/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} `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", "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} `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", "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} `profiles` List of available profiles.", "api": "requests", "name": "ListProfiles", "category": "profiles", "since": "4.0.0", "returns": [ { - "type": "Object|Array", + "type": "Array", "name": "profiles", "description": "List of available profiles." } @@ -2144,24 +2144,16 @@ { "subheads": [], "description": "List available scene collections", - "return": [ - "{Object|Array} `scene-collections` Scene collections list", - "{String} `scene-collections.*.`" - ], + "return": "{Array} `scene-collections` Scene collections list", "api": "requests", "name": "ListSceneCollections", "category": "scene collections", "since": "4.0.0", "returns": [ { - "type": "Object|Array", + "type": "Array", "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} `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", "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} `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", "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} `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", "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} `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", "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} `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", "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} `sources`" ], "api": "requests", "name": "GetPreviewScene", @@ -5316,7 +5308,7 @@ "description": "The name of the active preview scene." }, { - "type": "Source|Array", + "type": "Array", "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.", - "{String} `transitions[].name` Name of the transition." + "{Array} `transitions` List of transitions.", + "{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", "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} `sources` Ordered list of the current scene's source items." + ], + "properties": [ + { + "type": "String", + "name": "name", + "description": "Name of the currently active scene." + }, + { + "type": "Array", + "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": [] + } + ] } \ No newline at end of file diff --git a/docs/generated/protocol.md b/docs/generated/protocol.md index f1aa6c00..dffbaf01 100644 --- a/docs/generated/protocol.md +++ b/docs/generated/protocol.md @@ -43,6 +43,9 @@ auth_response = base64_encode(auth_response_hash) +- [Typedefs](#typedefs) + * [Scene](#scene) + * [Source](#source) - [Events](#events) * [Scenes](#scenes) + [SwitchScenes](#switchscenes) @@ -174,6 +177,31 @@ auth_response = base64_encode(auth_response_hash) +# 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<Source>_ | 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<Source>_ | 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<Source>_ | 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<Object>_ | List of available profiles. | --- @@ -1117,8 +1145,7 @@ _No specified parameters._ | Name | Type | Description | | ---- | :---: | ------------| -| `scene-collections` | _Object\|Array_ | Scene collections list | -| `scene-collections.*.` | _String_ | | +| `scene-collections` | _Array<String>_ | Scene collections list | --- @@ -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<Source>_ | 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<Scene>_ | 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<Object>_ | 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<Object>_ | 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<Object>_ | 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<Source>_ | | --- @@ -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[].name` | _String_ | Name of the transition. | +| `transitions` | _Array<Object>_ | List of transitions. | +| `transitions.*.name` | _String_ | Name of the transition. | --- diff --git a/docs/partials/typedefsHeader.md b/docs/partials/typedefsHeader.md new file mode 100644 index 00000000..2e1a057d --- /dev/null +++ b/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. diff --git a/docs/protocol.hbs b/docs/protocol.hbs index 313a5442..154491a1 100644 --- a/docs/protocol.hbs +++ b/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}} diff --git a/src/WSEvents.cpp b/src/WSEvents.cpp index 3df5abab..7bf30dc7 100644 --- a/src/WSEvents.cpp +++ b/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} `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} `sources` List of sources composing the scene. Same specification as [`GetCurrentScene`](#getcurrentscene). * * @api events * @name PreviewSceneChanged diff --git a/src/WSRequestHandler_Profiles.cpp b/src/WSRequestHandler_Profiles.cpp index e5812e6d..2a84b43c 100644 --- a/src/WSRequestHandler_Profiles.cpp +++ b/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} `profiles` List of available profiles. * * @api requests * @name ListProfiles diff --git a/src/WSRequestHandler_SceneCollections.cpp b/src/WSRequestHandler_SceneCollections.cpp index cd661f17..3c494a4e 100644 --- a/src/WSRequestHandler_SceneCollections.cpp +++ b/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 {String} `scene-collections.*.` + * @return {Array} `scene-collections` Scene collections list * * @api requests * @name ListSceneCollections diff --git a/src/WSRequestHandler_Scenes.cpp b/src/WSRequestHandler_Scenes.cpp index f15a76ac..822a822e 100644 --- a/src/WSRequestHandler_Scenes.cpp +++ b/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} `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} `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} `scenes` Ordered list of the current profile's scenes (See `[GetCurrentScene](#getcurrentscene)` for more information). * * @api requests * @name GetSceneList diff --git a/src/WSRequestHandler_Sources.cpp b/src/WSRequestHandler_Sources.cpp index 5f218066..bf62bbdf 100644 --- a/src/WSRequestHandler_Sources.cpp +++ b/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} `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} `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} `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 diff --git a/src/WSRequestHandler_StudioMode.cpp b/src/WSRequestHandler_StudioMode.cpp index 87a08ad1..41a2a46a 100644 --- a/src/WSRequestHandler_StudioMode.cpp +++ b/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} `sources` * * @api requests * @name GetPreviewScene diff --git a/src/WSRequestHandler_Transitions.cpp b/src/WSRequestHandler_Transitions.cpp index 776b37e4..45023b08 100644 --- a/src/WSRequestHandler_Transitions.cpp +++ b/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 {String} `transitions[].name` Name of the transition. + * @return {Array} `transitions` List of transitions. + * @return {String} `transitions.*.name` Name of the transition. * * @api requests * @name GetTransitionList