Skip to content

gst-webrtc-api: Improve JSDocs, add TypeScript type definitions

Piotr Brzeziński requested to merge thewildtree/gst-plugins-rs:gstwebrtc-api-typescript-defs into main 
* Moves some parts of the docs around to make them better parseable by
JSDoc (e.g. @classdesc moved to the constructor gets rid of duplicated
doc page for the entire class)

* Gets rid of unnecessary manual assignment of methods/properties
example: @method GstWebRTCAPI#createConsumerSession
Due to a bug in JSDoc, it doesn't automatically pick up docs in classes
marked with 'export default class ...'. Just making the export separate
is enough to fix this. I suppose this bug was why every documented part
was manually assigned to each class, and this is no longer necessary.

* Removes forced GstWebRTCAPI namespace from docs
I'm not sure why things were left this way, but at least since
563eff119303b572ce1f43378417ea8a80daebf6 our classes aren't actually in
any namespace (well, maybe apart from SessionState?), you can import
them one by one and no such namespace is present anywhere. I removed
that, kind of as a byproduct of the point above.

* Removes external: from type references
This is problematic because JSDoc handles this fine, but any IDE I've
tried couldn't parse those references correctly from the JSDocs, and
neither could the TypeScript compiler when autogenerating type
definitions. After removing the external: prefix, all tooling is picking
those types up fine, but JSDoc's docs end up losing links when refering
to said types. I left the definitions in index.js, so that they still
show up in the sidebar and can be easily referred to.

* Adds TypeScript type definitions (d.ts)
Those are autogenerated by running `npx tsc` in the main dir and then
manually corrected by 1) removing all undocumented ('private') functions
and 2) writing definitions for the Listener interfaces which TS can't
automatically infer from JSDocs. This makes it much easier to use our
library in TypeScript-based projects.

I tried my best to keep the resulting JSDoc generated documentation without any breaking changes, actually also removing some clutter, like duplicated docs for the GstWebRTCAPI class (due to the constructor having an optional arg which made JSDoc confused).

I would appreciate a second look to verify if I didn't miss anything there.

I know that the external: change might not be the most desirable, but I aimed for a middle ground between generated docs being usable and any tooling (TS compiler and any IDEs using it for parsing JSDocs) also being able to recognize the mentioned types.

Merge request reports