This is the documentation for obs-websocket. Run `build_docs.sh` to auto generate the latest docs from the `src` directory. There are 3 components to the docs generation:
-`comments/comments.js`: Generates the `work/comments.json` file from the code comments in the src directory.
-`docs/process_comments.py`: Processes `work/comments.json` to create `generated/protocol.json`, which is a machine-readable documentation format that can be used to create obs-websocket client libraries.
-`docs/generate_md.py`: Processes `generated/protocol.json` to create `generated/protocol.md`, which is the actual human-readable documentation.
Some notes about documenting:
- The `complexity` comment line is a suggestion to the user about how much knowledge about OBS's inner workings is required to safely use the associated feature. `1` for easy, `5` for megadeath-expert.
- The `rpcVersion` comment line is used to specify the latest available version that the feature is available in. If a feature is deprecated, then the placeholder value of `-1` should be replaced with the last RPC version that the feature will be available in. Manually specifying an RPC version automatically adds the `Deprecated` line to the entry in `generated/protocol.md`.
- The description can be multiple lines, but must be contained above the first documentation property (the lines starting with `@`).
- Value types are in reference to JSON values. The only ones you should use are `Any`, `String`, `Boolean`, `Number`, `Array`, `Object`.
-`Array` types follow this format: `Array<subtype>`, for example `Array<String>` to specify an array of strings.
Formatting notes:
- Fields should have their columns aligned. So in a request, the columns of all `@requestField`s should be aligned.
- We suggest looking at how other enums/events/requests have been documented before documenting one of your own, to get a general feel of how things have been formatted.
## Creating enum documentation
Enums follow this code comment format:
```js
/**
* [description]
*
*@enumIdentifier [identifier]
*@enumValue [value]
*@enumType [type]
*@rpcVersion [latest available RPC version, use `-1` unless deprecated.]
*@initialVersion [first obs-websocket version this is found in]
*@api enums
*/
```
Example code comment:
```js
/**
* The initial message sent by obs-websocket to newly connected clients.
*
*@enumIdentifier Hello
*@enumValue 0
*@enumType WebSocketOpCode
*@rpcVersion -1
*@initialVersion 5.0.0
*@api enums
*/
```
- This is the documentation for the `WebSocketOpCode::Hello` enum identifier.
*@requestField [optional flag][field name] | [value type] | [field description] | [value restrictions (only include if the value type is `Number`)] | [default behavior (only include if optional flag is set)]
