Improve documentation

include/find/find_sources.d.ts

@@ -1,3 +1,8 @@
 import type { SourceInstance } from './source_instance';
 
+/**
+ * Calls the NDI API to retrieve a list of {@link SourceInstance}s
+ * exposed into the network.
+ * @param timeout The maximum timeout to keep waiting for the list of sources
+ */
 export function findSources (timeout?: number): Promise<SourceInstance[]>;

include/find/find_sources.h

@@ -3,6 +3,13 @@
 #ifndef _SRC_FIND_FIND_SOURCES_H_
 #define _SRC_FIND_FIND_SOURCES_H_
 
+/**
+ * Calls `NDIlib_find_get_current_sources` and retrieves the list of
+ * the available sources to be retrieved.
+ *
+ * If no sources are available, or the `NDIlib_find_wait_for_sources`
+ * call fails, retrieves an empty list.
+ */
 Napi::Value FindSources(const Napi::CallbackInfo&);
 
 #endif

include/find/source_instance.d.ts

@@ -1,9 +1,16 @@
 import { TallyState } from '../structures/tally_state';
 
+/**
+ * An instance of an NDI (sender/receiver) source
+ */
 export interface SourceInstance {
+    /** Sets the tally state of the source instance */
     setTally (tallyState: TallyState): void;
 
+    /** Retrieves the IP Address of the instance */
     get ipAddress(): string;
+    /** Retrieves the name of the instance */
     get name(): string;
+    /** Retrieves the URL Address of the instance */
     get urlAddress(): string;
 }

include/find/source_instance.h

@@ -4,19 +4,27 @@
 #ifndef _SRC_STRUCTURES_SOURCE_INSTANCE_H_
 #define _SRC_STRUCTURES_SOURCE_INSTANCE_H_
 
+/**
+ * An instance of an NDI (send/recv) source
+ */
 class SourceInstance : public Napi::ObjectWrap<SourceInstance> {
 public:
   static void Init(Napi::Env env, Napi::Object exports);
   static Napi::Object New(Napi::Env env, NDIlib_source_t *ndiSourceInstance);
   static Napi::FunctionReference constructor;
 
+  /** Initializes an instance of a sender/receiver source */
   SourceInstance(const Napi::CallbackInfo &info);
   ~SourceInstance();
 
+  /** Sets the tally state of the source instance */
   void SetTally(const Napi::CallbackInfo &info);
 
+  /** Retrieves the IP Address of the instance */
   Napi::Value GetIpAddress(const Napi::CallbackInfo &info);
+  /** Retrieves the name of the instance */
   Napi::Value GetName(const Napi::CallbackInfo &info);
+  /** Retrieves the URL Address of the instance */
   Napi::Value GetUrlAddress(const Napi::CallbackInfo &info);
 
 

include/send/send_create.d.ts

@@ -1,4 +1,8 @@
-export interface SendCreate {
+/**
+ * This structure holds the options used for creating a send (output) video
+ * source
+ */
+export interface SendCreateOptions {
   /**
    * The name of the send video source.
    */

include/send/send_create.h

@@ -4,9 +4,20 @@
 #ifndef _SRC_SEND_SEND_CREATE_H_
 #define _SRC_SEND_SEND_CREATE_H_
 
-class SendCreate : Napi::Object {
+/**
+ * This structure holds the options used for creating a send (output) video
+ * source
+ */
+class SendCreateOptions : Napi::Object {
 public:
-  SendCreate(const Napi::Object &object);
+  /**
+   * Constructs an instance of SendCreateOptions, which holds the
+   * options for creating a `SendInstance`
+   */
+  SendCreateOptions(const Napi::Object &object);
+  /**
+   * A cast operator between this object and the `NDIlib_send_create_t` struct
+   */
   operator NDIlib_send_create_t() const;
 };
 

include/send/send_instance.d.ts

@@ -1,9 +1,21 @@
 import { AudioFrame } from '../structures/audio_frame';
 import { VideoFrame } from '../structures/video_frame';
-import { SendCreate } from './send_create';
+import { SendCreateOptions } from './send_create';
 
+/**
+ * A send (output) NDI instance
+ */
 export class SendInstance {
-  initialize(initParameters: SendCreate): void;
+  /**
+   * Initializes an instance for sending video
+   * @param initParameters The options to initialize the instance
+   */
+  initialize(initParameters: SendCreateOptions): void;
+  /**
+   * Sends a raw representation of frames (each one containing
+   * a {@link VideoFrame} and {@link AudioFrame}) into the NDI protocol.
+   * @param frames The video/audio frames to be sent into the network
+   */
   send(frames: {
     video?: VideoFrame,
     audio?: AudioFrame

include/structures/audio_frame.d.ts

@@ -1,3 +1,7 @@
+/**
+ * This structure represents the binary buffers for a multi-channel audio
+ * "frame" (being this frame a second of audio), with a specified sample rate.
+ */
 export interface AudioFrame {
   /**
    * This is the current audio sample rate. For instance, this might be 44100, 48000 or 96000.
@@ -7,7 +11,7 @@ export interface AudioFrame {
 
   /**
    * This is the floating-point audio data in planar format, split in channels,
-   * with each channel being a Float32Array.
+   * with each channel being a {@link Float32Array}.
    *
    * ```js
    * [

include/structures/video_frame.d.ts

@@ -1,13 +1,32 @@
+/**
+ * This structure holds the metadata and binary
+ * representation of a single frame of video, that can
+ * be sent into an encoder or decoder
+ */
 export interface VideoFrame {
+  /** The height of the video frame */
   height: number;
+  /** The width of the video frame */
   width: number;
 
+  /**
+   * The coulourspace format of the frame. This helps encoders/decoders
+   * figure out how to read the video buffer
+   */
   colourSpace: VideoColourSpace;
+  /**
+   * This metadata is used for the video source to understand the
+   * frame is part of a video stream of a certain framerate.
+   */
   framerate: VideoFramerate;
-
+  /** A buffer-like binary representation of the video frame */
   data: Buffer | Uint8Array;
 }
 
+/**
+ * The possible values for the colourspace
+ * for which a certain frame is encoded
+ */
 export enum VideoColourSpace {
   UYVY = 1,
   UYVA = 2,
@@ -22,6 +41,10 @@ export enum VideoColourSpace {
   RGBX = 11,
 }
 
+/**
+ * The possible values for the framerate at
+ * which a video stream is being encoded
+ */
 export enum VideoFramerate {
   F24 = 1,
   F2498 = 2,

src/send/send_create.cpp

@@ -3,11 +3,16 @@
 
 using namespace std;
 
-SendCreate::SendCreate(
+/**
+ * Constructs an instance of SendCreateOptions, which holds the
+ * options for creating a `SendInstance`
+ */
+SendCreateOptions::SendCreateOptions(
     const Napi::Object &object)
     : Napi::Object(object) {}
 
-SendCreate::operator NDIlib_send_create_t() const {
+
+SendCreateOptions::operator NDIlib_send_create_t() const {
   NDIlib_send_create_t sendCreateParams;
 
   if (!this->Has("name") || this->Get("name").IsUndefined()) {

src/send/send_instance.cpp

@@ -27,7 +27,7 @@ void SendInstance::Initialize(const Napi::CallbackInfo &info) {
 
   // Initialize sendCreate parameters using the initParameters argument
   try {
-    NDIlib_send_create_t sendCreateParams = (SendCreate)info[0].ToObject();
+    NDIlib_send_create_t sendCreateParams = (SendCreateOptions)info[0].ToObject();
 
     this->ndiSendInstance = NDIlib_send_create(&sendCreateParams);