feat(hooks): add doc strings for each hook

damienbutt · damienbutt · commit e58e89fc63b0 · 2022-04-24T22:59:11.000+01:00
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -16,5 +16,6 @@
         "**/.DS_Store": true,
         "**/*.js.map": true,
         "node_modules": true
-    }
+    },
+    "docwriter.progress.trackFunctions": true
 }
diff --git a/src/hooks/useCrestronAnalog/index.ts b/src/hooks/useCrestronAnalog/index.ts
@@ -2,6 +2,13 @@ import { AnalogStateCallback, IAnalogSignal } from "../../types";
 import { useCrestronPublishAnalog } from "../useCrestronPublishAnalog";
 import { useCrestronSubscribeAnalog } from "../useCrestronSubscribeAnalog";
 
+/**
+ * `useCrestronAnalog` is a hook that returns an object with a state and action property.
+ * @param {string} signalName - The name of the signal you want to use.
+ * @param {AnalogStateCallback} [callback] - An optional callback function that will be called whenever the state of the signal
+ * changes.
+ * @returns An array with a single IAnalogSignal object.
+ */
 export function useCrestronAnalog(
     signalName: string,
     callback?: AnalogStateCallback,
diff --git a/src/hooks/useCrestronAnalogCollection/index.ts b/src/hooks/useCrestronAnalogCollection/index.ts
@@ -8,6 +8,14 @@ import { getSignalCollection } from "../../utils";
 import { useCrestronPublishAnalogCollection } from "../useCrestronPublishAnalogCollection";
 import { useCrestronSubscribeAnalogCollection } from "../useCrestronSubscribeAnalogCollection";
 
+/**
+ * `useCrestronAnalogCollection` is a hook that returns an array of objects each with state and action properties.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to use.
+ * @param {AnalogStateCallback} [callback] - A optional callback function that will be called whenever the state of
+ * the signal changes.
+ * @returns An array of IAnalogSignal objects.
+ */
 export function useCrestronAnalogCollection(
     signalNames: string[],
     callback?: AnalogStateCallback,
diff --git a/src/hooks/useCrestronDigital/index.ts b/src/hooks/useCrestronDigital/index.ts
@@ -2,6 +2,13 @@ import { DigitalStateCallback, IDigitalSignal } from "../../types";
 import { useCrestronPublishDigital } from "../useCrestronPublishDigital";
 import { useCrestronSubscribeDigital } from "../useCrestronSubscribeDigital";
 
+/**
+ * `useCrestronDigital` is a hook that returns an object with a state and action property.
+ * @param {string} signalName - The name of the signal you want to use.
+ * @param {DigitalStateCallback} [callback] - An optional callback function that will be called whenever the state of the signal
+ * changes.
+ * @returns An array with a single IDigitalSignal object
+ */
 export function useCrestronDigital(
     signalName: string,
     callback?: DigitalStateCallback,
diff --git a/src/hooks/useCrestronDigitalCollection/index.ts b/src/hooks/useCrestronDigitalCollection/index.ts
@@ -8,6 +8,14 @@ import { getSignalCollection } from "../../utils";
 import { useCrestronPublishDigitalCollection } from "../useCrestronPublishDigitalCollection";
 import { useCrestronSubscribeDigitalCollection } from "../useCrestronSubscribeDigitalCollection";
 
+/**
+ * `useCrestronDigitalCollection` is a hook that returns an array of objects each with state and action properties.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to use.
+ * @param {DigitalStateCallback} [callback] - A optional callback function that will be called whenever the state of
+ * the signal changes.
+ * @returns An array of IDigitalSignal objects.
+ */
 export function useCrestronDigitalCollection(
     signalNames: string[],
     callback?: DigitalStateCallback,
diff --git a/src/hooks/useCrestronPublishAnalog/index.ts b/src/hooks/useCrestronPublishAnalog/index.ts
@@ -2,6 +2,11 @@ import { publishEvent } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { IAnalogEventAction } from "../../types";
 
+/**
+ * `useCrestronPublishAnalog` is a hook that returns an object with a setValue function.
+ * @param {string} signalName - The name of the signal you want to publish to.
+ * @returns An array with a single IAnalogEventAction object.
+ */
 export function useCrestronPublishAnalog(
     signalName: string,
 ): [IAnalogEventAction] {
diff --git a/src/hooks/useCrestronPublishAnalogCollection/index.ts b/src/hooks/useCrestronPublishAnalogCollection/index.ts
@@ -2,6 +2,12 @@ import { publishEvent } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { IAnalogEventAction } from "../../types";
 
+/**
+ * `useCrestronPublishAnalogCollection` is a hook that returns an array of objects each with a setValue function.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to publish to.
+ * @returns An array of IAnalogEventAction objects.
+ */
 export function useCrestronPublishAnalogCollection(
     signalNames: string[],
 ): IAnalogEventAction[] {
diff --git a/src/hooks/useCrestronPublishDigital/index.ts b/src/hooks/useCrestronPublishDigital/index.ts
@@ -2,6 +2,11 @@ import { publishEvent } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { IDigitalEventAction } from "../../types";
 
+/**
+ * `useCrestronPublishDigital` is a hook that returns an object with setValue, push, release and click functions.
+ * @param {string} signalName - The name of the signal you want to publish to.
+ * @returns An array with a single IDigitalEventAction object.
+ */
 export function useCrestronPublishDigital(
     signalName: string,
 ): [IDigitalEventAction] {
diff --git a/src/hooks/useCrestronPublishDigitalCollection/index.ts b/src/hooks/useCrestronPublishDigitalCollection/index.ts
@@ -2,6 +2,12 @@ import { publishEvent } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { IDigitalEventAction } from "../../types";
 
+/**
+ * `useCrestronPublishDigitalCollection` is a hook that returns an array of objects each with setValue, push, release and click functions.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to publish to.
+ * @returns An array of IDigitalEventAction objects.
+ */
 export function useCrestronPublishDigitalCollection(
     signalNames: string[],
 ): IDigitalEventAction[] {
diff --git a/src/hooks/useCrestronPublishSerial/index.ts b/src/hooks/useCrestronPublishSerial/index.ts
@@ -2,6 +2,11 @@ import { publishEvent } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { ISerialEventAction } from "../../types";
 
+/**
+ * `useCrestronPublishSerial` is a hook that returns an object with a setValue function.
+ * @param {string} signalName - The name of the signal you want to publish to.
+ * @returns An array with a single ISerialEventAction object.
+ */
 export function useCrestronPublishSerial(
     signalName: string,
 ): [ISerialEventAction] {
diff --git a/src/hooks/useCrestronPublishSerialCollection/index.ts b/src/hooks/useCrestronPublishSerialCollection/index.ts
@@ -2,6 +2,12 @@ import { publishEvent } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { ISerialEventAction } from "../../types";
 
+/**
+ * `useCrestronPublishSerialCollection` is a hook that returns an array of objects each with a setValue function.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to publish to.
+ * @returns An array of ISerialEventAction objects.
+ */
 export function useCrestronPublishSerialCollection(
     signalNames: string[],
 ): ISerialEventAction[] {
diff --git a/src/hooks/useCrestronSerial/index.ts b/src/hooks/useCrestronSerial/index.ts
@@ -2,6 +2,13 @@ import { ISerialSignal, SerialStateCallback } from "../../types";
 import { useCrestronPublishSerial } from "../useCrestronPublishSerial";
 import { useCrestronSubscribeSerial } from "../useCrestronSubscribeSerial";
 
+/**
+ * `useCrestronSerial` is a hook that returns an object with a state and action property.
+ * @param {string} signalName - The name of the signal you want to use.
+ * @param {SerialStateCallback} [callback] - An optional callback function that will be called whenever the state of the signal
+ * changes.
+ * @returns An array with a single ISerialSignal object.
+ */
 export function useCrestronSerial(
     signalName: string,
     callback?: SerialStateCallback,
diff --git a/src/hooks/useCrestronSerialCollection/index.ts b/src/hooks/useCrestronSerialCollection/index.ts
@@ -8,6 +8,14 @@ import { getSignalCollection } from "../../utils";
 import { useCrestronPublishSerialCollection } from "../useCrestronPublishSerialCollection";
 import { useCrestronSubscribeSerialCollection } from "../useCrestronSubscribeSerialCollection";
 
+/**
+ * `useCrestronSerialCollection` is a hook that returns an array of objects each with state and action properties.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to use.
+ * @param {SerialStateCallback} [callback] - A optional callback function that will be called whenever the state of
+ * the signal changes.
+ * @returns An array of ISerialSignal objects.
+ */
 export function useCrestronSerialCollection(
     signalNames: string[],
     callback?: SerialStateCallback,
diff --git a/src/hooks/useCrestronSubscribeAnalog/index.ts b/src/hooks/useCrestronSubscribeAnalog/index.ts
@@ -3,6 +3,13 @@ import { subscribeState, unsubscribeState } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { AnalogStateCallback, IAnalogState } from "../../types";
 
+/**
+ * `useCrestronSubscribeAnalog` is a hook that returns an object with a value property.
+ * @param {string} signalName - The name of the signal you want to subscribe to.
+ * @param {AnalogStateCallback} [callback] - An optional callback function that will be called whenever the state
+ * changes.
+ * @returns An array with a single IAnalogState object.
+ */
 export function useCrestronSubscribeAnalog(
     signalName: string,
     callback?: AnalogStateCallback,
diff --git a/src/hooks/useCrestronSubscribeAnalogCollection/index.ts b/src/hooks/useCrestronSubscribeAnalogCollection/index.ts
@@ -7,6 +7,14 @@ import {
     IStateSubscription,
 } from "../../types";
 
+/**
+ * `useCrestronSubscribeAnalogCollection` is a hook that returns an array of objects each with a value property.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to subscribe to.
+ * @param {AnalogStateCallback} [callback] - An optional callback function that will be called whenever the
+ * state changes.
+ * @returns An array of IAnalogState objects.
+ */
 export function useCrestronSubscribeAnalogCollection(
     signalNames: string[],
     callback?: AnalogStateCallback,
diff --git a/src/hooks/useCrestronSubscribeDigital/index.ts b/src/hooks/useCrestronSubscribeDigital/index.ts
@@ -3,6 +3,13 @@ import { subscribeState, unsubscribeState } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { DigitalStateCallback, IDigitalState } from "../../types";
 
+/**
+ * `useCrestronSubscribeDigital` is a hook that returns an object with a value property.
+ * @param {string} signalName - The name of the signal you want to subscribe to.
+ * @param {DigitalStateCallback} [callback] - An optional callback function that will be called whenever the state
+ * changes.
+ * @returns An array with a single IDigitalState object.
+ */
 export function useCrestronSubscribeDigital(
     signalName: string,
     callback?: DigitalStateCallback,
diff --git a/src/hooks/useCrestronSubscribeDigitalCollection/index.ts b/src/hooks/useCrestronSubscribeDigitalCollection/index.ts
@@ -7,6 +7,14 @@ import {
     IStateSubscription,
 } from "../../types";
 
+/**
+ * `useCrestronSubscribeDigitalCollection` is a hook that returns an array of objects each with a value property.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to subscribe to.
+ * @param {DigitalStateCallback} [callback] - An optional callback function that will be called whenever the
+ * state changes.
+ * @returns An array of IDigitalState objects.
+ */
 export function useCrestronSubscribeDigitalCollection(
     signalNames: string[],
     callback?: DigitalStateCallback,
diff --git a/src/hooks/useCrestronSubscribeSerial/index.ts b/src/hooks/useCrestronSubscribeSerial/index.ts
@@ -3,6 +3,13 @@ import { subscribeState, unsubscribeState } from "@crestron/ch5-crcomlib";
 import CrestronCH5 from "@norgate-av/crestron-ch5-helper";
 import { ISerialState, SerialStateCallback } from "../../types";
 
+/**
+ * `useCrestronSubscribeSerial` is a hook that returns an object with a value property.
+ * @param {string} signalName - The name of the signal you want to subscribe to.
+ * @param {SerialStateCallback} [callback] - An optional callback function that will be called whenever the state
+ * changes.
+ * @returns An array with a single ISerialState object.
+ */
 export function useCrestronSubscribeSerial(
     signalName: string,
     callback?: SerialStateCallback,
diff --git a/src/hooks/useCrestronSubscribeSerialCollection/index.ts b/src/hooks/useCrestronSubscribeSerialCollection/index.ts
@@ -7,6 +7,14 @@ import {
     ISerialState,
 } from "../../types";
 
+/**
+ * `useCrestronSubscribeSerialCollection` is a hook that returns an array of objects each with a value property.
+ * @param {string[]} signalNames - An array of strings that represent the names of the signals you want
+ * to subscribe to.
+ * @param {SerialStateCallback} [callback] - An optional callback function that will be called whenever the
+ * state changes.
+ * @returns An array of ISerialState objects.
+ */
 export function useCrestronSubscribeSerialCollection(
     signalNames: string[],
     callback?: SerialStateCallback,

Original file line number	Diff line number	Diff line change
`@@ -16,5 +16,6 @@`
`16`	`16`	`"**/.DS_Store": true,`
`17`	`17`	`"*/.js.map": true,`
`18`	`18`	`"node_modules": true`
`19`		`- }`
	`19`	`+ },`
	`20`	`+ "docwriter.progress.trackFunctions": true`
`20`	`21`	`}`