Merge pull request #3 from mathworks-continuous-integration/jpereira/docstrings

Add docstrings

Author: jwpereira

src/index.ts

@@ -6,6 +6,9 @@ import * as matlab from "./matlab";
 
 export { matlab };
 
+/**
+ * Gather action inputs and then run action.
+ */
 async function run() {
     const platform = process.platform;
     const workspaceDir = process.cwd();

src/matlab.ts

@@ -6,13 +6,27 @@ import * as path from "path";
 import { v4 as uuid } from "uuid";
 import * as script from "./script";
 
+/**
+ * Helper interface to represent a MATLAB script.
+ */
 export interface HelperScript {
     dir: string;
     command: string;
 }
 
+/**
+ * Type of a function that executes a command on a runner and returns the error
+ * code.
+ */
 export type ExecFn = (command: string, args?: string[]) => Promise<number>;
 
+/**
+ * Generate a MATLAB script in the temporary directory that runs a command in
+ * the workspace.
+ *
+ * @param workspaceDir CI job workspace directory
+ * @param command MATLAB command to run
+ */
 export async function generateScript(workspaceDir: string, command: string): Promise<HelperScript> {
     const scriptName = script.safeName(`command_${uuid()}`);
 
@@ -26,6 +40,15 @@ export async function generateScript(workspaceDir: string, command: string): Pro
     return { dir: temporaryDirectory, command: scriptName };
 }
 
+/**
+ * Run a HelperScript in MATLAB.
+ *
+ * Create the HelperScript using `generateScript`.
+ *
+ * @param hs HelperScript pointing to the script containing the command
+ * @param platform Operating system of the runner (e.g., "win32" or "linux")
+ * @param fn ExecFn that will execute a command on the runner
+ */
 export async function runCommand(hs: HelperScript, platform: string, fn: ExecFn): Promise<void> {
     const rmcPath = getRmcPath(platform);
     await fs.chmod(rmcPath, 0o777);
@@ -38,6 +61,11 @@ export async function runCommand(hs: HelperScript, platform: string, fn: ExecFn)
     }
 }
 
+/**
+ * Get the path of the script containing RunMATLABCommand for the host OS.
+ *
+ * @param platform Operating system of the runner (e.g., "win32" or "linux")
+ */
 export function getRmcPath(platform: string): string {
     const ext = platform === "win32" ? "bat" : "sh";
     const rmcPath = path.join(__dirname, "bin", `run_matlab_command.${ext}`);

src/script.ts

@@ -1,13 +1,31 @@
 // Copyright 2020 The MathWorks, Inc.
 
+/**
+ * Generate MATLAB command for changing directories and calling a command in it.
+ *
+ * @param dir Directory to change to.
+ * @param command Command to run in directory.
+ * @returns MATLAB command.
+ */
 export function cdAndCall(dir: string, command: string): string {
     return `cd('${pathToCharVec(dir)}'); ${command}`;
 }
 
+/**
+ * Convert a path-like string to MATLAB character vector literal.
+ *
+ * @param s Input string.
+ * @returns Input string in MATLAB character vector literal.
+ */
 export function pathToCharVec(s: string): string {
     return s.replace(/'/g, "''");
 }
 
+/**
+ * Convert an identifier (i.e., a script name) to one that is callable by MATLAB.
+ *
+ * @param s Input identifier.
+ */
 export function safeName(s: string): string {
     return s.replace(/-/g, "_");
 }