Skip to content
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

Open
wants to merge 5 commits into
base: master
Choose a base branch
from

Conversation

Abrahamic-God
Copy link

Description

This PR adds protocol documentation for the objects used.

Motivation and Context

Currently, obs-websocket-js types many fields as JSONObjects, which is kind of useless. This PR adds much more detail about the objects used in the protocol, which then allows obs-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 of protocol.md, and verified that my changes to this repo and my upcoming corresponding changes to obs-websocket-js will work.

Types of changes

  • Documentation change (a change to documentation pages)

Checklist:

  • I have read the Contributing Guidelines.
  • All commit messages are properly formatted and commits squashed where appropriate.
  • My code is not on master or a release/* branch.
  • The code has been tested.
  • I have included updates to all appropriate documentation.

Added information about the properties present in the objects used in the protocol.
@@ -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
Copy link
Member

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"?

Copy link
Author

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 Partials 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.

@@ -19,6 +19,115 @@ with this program. If not, see <https://www.gnu.org/licenses/>

#pragma once

/**
Copy link
Member

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.

Copy link
Author

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.

* @api typedefs
*/

/**
Copy link
Member

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.

Copy link
Author

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants