New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Add custom object typedefs #1091
base: master
Are you sure you want to change the base?
docs: Add custom object typedefs #1091
Conversation
Added information about the properties present in the objects used in the protocol.
cf58642
to
0ffafe0
Compare
@@ -228,7 +228,7 @@ void EventHandler::HandleSceneItemSelected(void *param, calldata_t *data) | |||
* | |||
* @dataField sceneName | String | The name of the scene the item is in | |||
* @dataField sceneItemId | Number | Numeric ID of the scene item | |||
* @dataField sceneItemTransform | Object | New transform/crop info of the scene item | |||
* @dataField sceneItemTransform | Partial<SceneItemTransform> | New transform/crop info of the scene item |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You're introducing the concept of a partial object (which is fine of course), but I don't see this specified anywhere that it's a typedef within an array. Is there something I'm missing?
In theory, pretty much every returned object in obs-websocket is partial. Perhaps it would be better to just make a blanket statement calling all objects returned by obs-websocket "partial"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That particular line is a mistake and was not meant to be a partial. It will always return the full SceneItemTransform
object every time.
Where Partial
s are meant to be used is in requests such as RequestHandler::SetSceneItemTransform
, because the requestor is NOT required to specify a value for every property, only the properties they intend to update. I think this distinction is worth specifying via the Partial
keyword. However, as it stands now, Partial
is used in exactly one place.
src/obs-websocket.h
Outdated
@@ -19,6 +19,115 @@ with this program. If not, see <https://www.gnu.org/licenses/> | |||
|
|||
#pragma once | |||
|
|||
/** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would be best to define these individually wherever these objects are most created, be it things like the utils code files or request/event files. Just to align with how documentation is currently done for these.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I moved them around, let me know if what I did aligns with what you were thinking or if there's even better places for them.
src/obs-websocket.h
Outdated
* @api typedefs | ||
*/ | ||
|
||
/** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would personally think it would be good to include other fields not explicitly returned in a request as an object in these typedefs. For example, inputSettings
is never included as an Input
object, but is very much associated with inputs. Let me know your thoughts.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I can go through and type everything currently typed as an Object
, if you like. Sound good?
Description
This PR adds protocol documentation for the objects used.
Motivation and Context
Currently,
obs-websocket-js
types many fields asJSONObjects
, which is kind of useless. This PR adds much more detail about the objects used in the protocol, which then allowsobs-websocket-js
to generate more accurate and useful typedefs.How Has This Been Tested?
I modified
obs-websocket-js
' types generation script to run on a locally-present version ofprotocol.md
, and verified that my changes to this repo and my upcoming corresponding changes toobs-websocket-js
will work.Types of changes
Checklist:
master
or arelease/*
branch.