add file and function level docstrings

index.js

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 
+/**
+ * @file index.js
+ * @module index
+ * @description
+ * Main entry point for the Meld CLI application.
+ */
+
 import { QWebChannel } from 'qwebchannel'
 import WebSocket from 'ws'
 

utils/audio.js

@@ -1,3 +1,12 @@
+/**
+ * @file audio.js
+ * @module utils/audio
+ * @description
+ * Utilities for managing audio tracks in a Meld session via CLI.
+ * Provides commands to list, mute, unmute, toggle, and check the status of audio tracks.
+ * Integrates with cli-meow-help for command-line help and cli-table3 for tabular output.
+ */
+
 import meowHelp from 'cli-meow-help'
 import Table from 'cli-table3'
 
@@ -29,14 +38,30 @@ const flags = {
   }
 }
 
+/**
+ * Contains the help information for the audio command group.
+ *
+ * @type {object}
+ * @property {string} name - The name of the CLI command.
+ * @property {string} desc - Description of the command's purpose.
+ * @property {object} commands - The available subcommands.
+ * @property {object} flags - The available flags for the command.
+ * @property {boolean} defaults - Indicates if default values are shown.
+ */
 const audioHelp = meowHelp({
   name: 'meld-cli audio',
-  flags,
-  commands,
   desc: 'Manage audio settings in Meld',
+  commands,
+  flags,
   defaults: false
 })
 
+/**
+ * List all audio tracks in the Meld session.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @param {boolean} showId - Whether to display the audio track ID.
+ * @returns {Promise<Table|string>} Resolves with a Table instance or a message if no devices found.
+ */
 function audioList (channel, showId) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -71,6 +96,12 @@ function audioList (channel, showId) {
   return Promise.resolve(table)
 }
 
+/**
+ * Mute a specific audio track by name.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @param {string} audioName - The name of the audio track to mute.
+ * @returns {Promise<string>} Resolves with a success message or rejects with an error.
+ */
 function audioMute (channel, audioName) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -104,6 +135,12 @@ function audioMute (channel, audioName) {
   })
 }
 
+/**
+ * Unmute a specific audio track by name.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @param {string} audioName - The name of the audio track to unmute.
+ * @returns {Promise<string>} Resolves with a success message or rejects with an error.
+ */
 function audioUnmute (channel, audioName) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -136,6 +173,12 @@ function audioUnmute (channel, audioName) {
   })
 }
 
+/**
+ * Toggle the mute state of a specific audio track by name.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @param {string} audioName - The name of the audio track to toggle.
+ * @returns {Promise<string>} Resolves with a message indicating the new state or rejects with an error.
+ */
 function audioToggle (channel, audioName) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -166,6 +209,12 @@ function audioToggle (channel, audioName) {
   })
 }
 
+/**
+ * Get the mute status of a specific audio track by name.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @param {string} audioName - The name of the audio track to check.
+ * @returns {Promise<string>} Resolves with the current mute status or rejects with an error.
+ */
 function audioStatus (channel, audioName) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))

utils/clip.js

@@ -1,5 +1,24 @@
+/**
+ * @file clip.js
+ * @module utils/clip
+ * @description
+ * Utilities for managing clips in a Meld session via CLI.
+ * Provides commands to save clips and display help information.
+ * Integrates with cli-meow-help for command-line help.
+ */
+
 import meowHelp from 'cli-meow-help'
 
+/**
+ * Contains the help information for the clip command group.
+ *
+ * @type {object}
+ * @property {string} name - The name of the CLI command.
+ * @property {string} desc - Description of the command's purpose.
+ * @property {object} commands - The available subcommands.
+ * @property {object} flags - The available flags for the command.
+ * @property {boolean} defaults - Indicates if default values are shown.
+ */
 const clipHelp = meowHelp({
   name: 'meld-cli clip',
   desc: 'Manage clips in Meld',
@@ -18,6 +37,11 @@ const clipHelp = meowHelp({
   defaults: false
 })
 
+/**
+ * Save a clip.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @returns {Promise<string>} Resolves with a success message or rejects with an error.
+ */
 async function clipSave (channel) {
   await channel.objects.meld.sendCommand('meld.recordClip')
   return 'Clip saved successfully.'

utils/record.js

@@ -1,3 +1,12 @@
+/**
+ * @file record.js
+ * @module utils/record
+ * @description
+ * Utilities for managing recording state in a Meld session via CLI.
+ * Provides commands to start, stop, toggle, and check the status of recording.
+ * Integrates with cli-meow-help for command-line help.
+ */
+
 import meowHelp from 'cli-meow-help'
 
 const commands = {
@@ -23,14 +32,30 @@ const flags = {
   }
 }
 
+/**
+ * Contains the help information for the record command group.
+ *
+ * @type {object}
+ * @property {string} name - The name of the CLI command.
+ * @property {string} desc - Description of the command's purpose.
+ * @property {object} commands - The available subcommands.
+ * @property {object} flags - The available flags for the command.
+ * @property {boolean} defaults - Indicates if default values are shown.
+ */
 const recordHelp = meowHelp({
   name: 'meld-cli record',
-  flags,
-  commands,
   desc: 'Manage recording in Meld',
+  commands,
+  flags,
   defaults: false
 })
 
+/**
+ * Start recording using the Meld object in the provided channel.
+ * @function
+ * @param {Object} channel - The channel object containing Meld.
+ * @returns {Promise<string>} Resolves with a success message or rejects with an error.
+ */
 function recordStart (channel) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -52,6 +77,12 @@ function recordStart (channel) {
   })
 }
 
+/**
+ * Stop recording using the Meld object in the provided channel.
+ * @function
+ * @param {Object} channel - The channel object containing Meld.
+ * @returns {Promise<string>} Resolves with a success message or rejects with an error.
+ */
 function recordStop (channel) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -73,6 +104,12 @@ function recordStop (channel) {
   })
 }
 
+/**
+ * Toggle the recording state using the Meld object in the provided channel.
+ * @function
+ * @param {Object} channel - The channel object containing Meld.
+ * @returns {Promise<string>} Resolves with a message indicating the new recording state or rejects with an error.
+ */
 function recordToggle (channel) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -90,6 +127,12 @@ function recordToggle (channel) {
   })
 }
 
+/**
+ * Get the current recording status from the Meld object in the provided channel.
+ * @function
+ * @param {Object} channel - The channel object containing Meld.
+ * @returns {Promise<string>} Resolves with a message indicating if recording is active or inactive.
+ */
 function recordStatus (channel) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))

utils/scene.js

@@ -1,3 +1,12 @@
+/**
+ * @file scene.js
+ * @module utils/scene
+ * @description
+ * Utilities for managing scenes in a Meld session via CLI.
+ * Provides commands to list, switch, and show the current scene.
+ * Integrates with cli-meow-help for command-line help and cli-table3 for tabular output.
+ */
+
 import meowHelp from 'cli-meow-help'
 import Table from 'cli-table3'
 
@@ -27,14 +36,30 @@ const flags = {
   }
 }
 
+/**
+ * Contains the help information for the scene command group.
+ *
+ * @type {object}
+ * @property {string} name - The name of the CLI command.
+ * @property {string} desc - Description of the command's purpose.
+ * @property {object} commands - The available subcommands.
+ * @property {object} flags - The available flags for the command.
+ * @property {boolean} defaults - Indicates if default values are shown.
+ */
 const sceneHelp = meowHelp({
   name: 'meld-cli scene',
-  flags,
-  commands,
   desc: 'Manage scenes in Meld',
+  commands,
+  flags,
   defaults: false
 })
 
+/**
+ * Lists all scenes in the current Meld session, optionally showing their IDs.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @param {boolean} showId - Whether to display scene IDs in the output.
+ * @returns {Promise<Table|string>} A promise that resolves to a Table instance or a message if no scenes are found.
+ */
 function sceneList (channel, showId) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -69,6 +94,12 @@ function sceneList (channel, showId) {
   return Promise.resolve(table)
 }
 
+/**
+ * Switches to a scene by its name.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @param {string} sceneName - The name of the scene to switch to.
+ * @returns {Promise<string>} A promise that resolves to a confirmation message or rejects if the scene is not found.
+ */
 function sceneSwitch (channel, sceneName) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -95,6 +126,12 @@ function sceneSwitch (channel, sceneName) {
   })
 }
 
+/**
+ * Shows the current active scene, optionally displaying its ID.
+ * @param {Object} channel - The channel object containing Meld session data.
+ * @param {boolean} showId - Whether to display the scene ID.
+ * @returns {Promise<string>} A promise that resolves to the current scene information or rejects if not found.
+ */
 function sceneCurrent (channel, showId) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))

utils/screenshot.js

@@ -1,5 +1,24 @@
+/**
+ * @file screenshot.js
+ * @module utils/screenshot
+ * @description
+ * Utilities for managing screenshots in a Meld session via CLI.
+ * Provides commands to take screenshots and display help information.
+ * Integrates with cli-meow-help for command-line help.
+ */
+
 import meowHelp from 'cli-meow-help'
 
+/**
+ * Contains the help information for the screenshot command group.
+ *
+ * @type {object}
+ * @property {string} name - The name of the CLI command.
+ * @property {string} desc - Description of the command's purpose.
+ * @property {object} commands - The available subcommands.
+ * @property {object} flags - The available flags for the command.
+ * @property {boolean} defaults - Indicates if default values are shown.
+ */
 const screenshotHelp = meowHelp({
   name: 'meld-cli screenshot',
   desc: 'Manage screenshots in Meld',
@@ -18,6 +37,13 @@ const screenshotHelp = meowHelp({
   defaults: false
 })
 
+/**
+ * Takes a screenshot by sending the 'meld.screenshot' command through the provided channel.
+ *
+ * @async
+ * @param {Object} channel - The communication channel with Meld.
+ * @returns {Promise<string>} Resolves with a success message when the screenshot is taken.
+ */
 async function screenshotTake (channel) {
   await channel.objects.meld.sendCommand('meld.screenshot')
   return 'Screenshot taken successfully.'

utils/stream.js

@@ -1,3 +1,12 @@
+/**
+ * @file stream.js
+ * @module utils/stream
+ * @description
+ * Utilities for managing streaming in a Meld session via CLI.
+ * Provides commands to start, stop, toggle, and check the status of streaming.
+ * Integrates with cli-meow-help for command-line help.
+ */
+
 import meowHelp from 'cli-meow-help'
 
 const commands = {
@@ -23,14 +32,30 @@ const flags = {
   }
 }
 
+/**
+ * Contains the help information for the stream command group.
+ *
+ * @type {object}
+ * @property {string} name - The name of the CLI command.
+ * @property {string} desc - Description of the command's purpose.
+ * @property {object} commands - The available subcommands.
+ * @property {object} flags - The available flags for the command.
+ * @property {boolean} defaults - Indicates if default values are shown.
+ */
 const streamHelp = meowHelp({
   name: 'meld-cli stream',
-  flags,
-  commands,
   desc: 'Manage streaming in Meld',
+  commands,
+  flags,
   defaults: false
 })
 
+/**
+ * Start streaming if not already active.
+ * @function
+ * @param {Object} channel - The channel object containing Meld.
+ * @returns {Promise<string>} Resolves with a success message or rejects with an error.
+ */
 function streamStart (channel) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -52,6 +77,13 @@ function streamStart (channel) {
   })
 }
 
+/**
+ * Stop streaming if currently active.
+ * @function
+ * @param {Object} channel - The channel object containing Meld.
+ * @returns {Promise<string>} Resolves with a success message or rejects with an error.
+ */
+
 function streamStop (channel) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -73,6 +105,12 @@ function streamStop (channel) {
   })
 }
 
+/**
+ * Toggle the streaming state.
+ * @function
+ * @param {Object} channel - The channel object containing Meld.
+ * @returns {Promise<string>} Resolves with a message indicating the new streaming state or rejects with an error.
+ */
 function streamToggle (channel) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))
@@ -90,6 +128,12 @@ function streamToggle (channel) {
   })
 }
 
+/**
+ * Get the current streaming status.
+ * @function
+ * @param {Object} channel - The channel object containing Meld.
+ * @returns {Promise<string>} Resolves with a message indicating whether streaming is active or inactive.
+ */
 function streamStatus (channel) {
   if (!channel.objects || !channel.objects.meld) {
     return Promise.reject(new Error('Meld object not found in channel.'))

utils/style.js

@@ -1,5 +1,17 @@
+/**
+ * @file style.js
+ * @module utils/style
+ * @description
+ * Utilities for styling console output in the Meld CLI.
+ */
+
 import clc from 'cli-color'
 
+/**
+ * Styles for console output in the Meld CLI.
+ * @constant
+ * @type {object}
+ */
 const style = {
   highlight: clc.cyan,
   err: clc.red.bold,

utils/virtualcam.js

@@ -1,3 +1,12 @@
+/**
+ * @file virtualcam.js
+ * @module utils/virtualcam
+ * @description
+ * Utilities for managing the virtual camera in a Meld session via CLI.
+ * Provides commands to toggle the virtual camera on or off.
+ * Integrates with cli-meow-help for command-line help.
+ */
+ 
 import meowHelp from 'cli-meow-help'
 
 const commands = {
@@ -14,14 +23,32 @@ const flags = {
   }
 }
 
+/**
+ * Contains the help information for the stream command group.
+ *
+ * @type {object}
+ * @property {string} name - The name of the CLI command.
+ * @property {string} desc - Description of the command's purpose.
+ * @property {object} commands - The available subcommands.
+ * @property {object} flags - The available flags for the command.
+ * @property {boolean} defaults - Indicates if default values are shown.
+ */
 const virtualcamHelp = meowHelp({
   name: 'virtualcam',
-  flags,
-  commands,
   desc: 'Manage virtual camera settings in Meld',
+  commands,
+  flags,
   defaults: false
 })
 
+/**
+ * Toggles the virtual camera on or off by sending a command through the provided channel.
+ *
+ * @async
+ * @function virtualcamToggle
+ * @param {object} channel - The channel object containing the 'meld' object for sending commands.
+ * @returns {Promise<string>} A promise that resolves to a success message upon toggling the virtual camera.
+ */
 async function virtualcamToggle (channel) {
   await channel.objects.meld.sendCommand('meld.toggleVirtualCameraAction')
   return 'Virtual camera toggled successfully.'