From 1f4b15cd59174ed148f7a874e4b712ddaecf2982 Mon Sep 17 00:00:00 2001
From: markw65 <mark_st@myosotissp.com>
Date: Mon, 11 Dec 2023 15:44:33 -0800
Subject: [PATCH] Add @returns everywhere

---
 lib/compiler/passes/generate-bytecode.js | 38 +++++++++++++++++++-----
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/lib/compiler/passes/generate-bytecode.js b/lib/compiler/passes/generate-bytecode.js
index f45e4398..b29f0046 100644
--- a/lib/compiler/passes/generate-bytecode.js
+++ b/lib/compiler/passes/generate-bytecode.js
@@ -292,14 +292,20 @@ function generateBytecode(ast, options) {
   /** @type PEG.LocationRange[] */
   const locations = [];
 
-  /** @param {string} value */
+  /**
+   * @param {string} value
+   * @returns {number}
+   */
   function addLiteralConst(value) {
     const index = literals.indexOf(value);
 
     return index === -1 ? literals.push(value) - 1 : index;
   }
 
-  /** @param {PEG.ast.CharacterClass} node */
+  /**
+   * @param {PEG.ast.CharacterClass} node
+   * @returns {number}
+   */
   function addClassConst(node) {
     const cls = {
       value: node.parts,
@@ -312,7 +318,10 @@ function generateBytecode(ast, options) {
     return index === -1 ? classes.push(cls) - 1 : index;
   }
 
-  /** @param {PEG.ast.GrammarExpectation} expected */
+  /**
+   * @param {PEG.ast.GrammarExpectation} expected
+   * @returns {number}
+   */
   function addExpectedConst(expected) {
     const pattern = JSON.stringify(expected);
     const index = expectations.findIndex(e => JSON.stringify(e) === pattern);
@@ -324,6 +333,7 @@ function generateBytecode(ast, options) {
    * @param {boolean} predicate
    * @param {string[]} params
    * @param {{code:string; codeLocation: PEG.LocationRange}} node
+   * @returns {number}
    */
   function addFunctionConst(predicate, params, node) {
     const func = {
@@ -338,7 +348,10 @@ function generateBytecode(ast, options) {
     return index === -1 ? functions.push(func) - 1 : index;
   }
 
-  /** @param {PEG.LocationRange} location */
+  /**
+   * @param {PEG.LocationRange} location
+   * @returns {number}
+   */
   function addLocation(location) {
     // Don't bother de-duplicating. There can be a lot of locations,
     // they will almost never collide, and unlike the "consts" above,
@@ -349,7 +362,10 @@ function generateBytecode(ast, options) {
   /** @typedef {Record<string, number>} Env */
   /** @typedef {{ sp: number; env:Env; action:PEG.ast.Action|null; pluck?: number[] }} Context */
 
-  /** @param {Env} env */
+  /**
+   * @param {Env} env
+   * @returns {Env}
+   */
   function cloneEnv(env) {
     /** @type {Env} */
     const clone = {};
@@ -364,6 +380,7 @@ function generateBytecode(ast, options) {
   /**
    * @param {number[]} first
    * @param {number[][]} args
+   * @returns {number[]}
    */
   function buildSequence(first, ...args) {
     return first.concat(...args);
@@ -374,6 +391,7 @@ function generateBytecode(ast, options) {
    * @param {number[]} condCode
    * @param {number[]} thenCode
    * @param {number[]} elseCode
+   * @returns {number[]}
    */
   function buildCondition(match, condCode, thenCode, elseCode) {
     if (match === ALWAYS_MATCH) { return thenCode; }
@@ -389,6 +407,7 @@ function generateBytecode(ast, options) {
   /**
    * @param {number[]} condCode
    * @param {number[]} bodyCode
+   * @returns {number[]}
    */
   function buildLoop(condCode, bodyCode) {
     return condCode.concat([bodyCode.length], bodyCode);
@@ -399,6 +418,7 @@ function generateBytecode(ast, options) {
    * @param {number} delta
    * @param {Env} env
    * @param {number} sp
+   * @returns {number[]}
    */
   function buildCall(functionIndex, delta, env, sp) {
     const params = Object.keys(env).map(name => sp - env[name]);
@@ -411,6 +431,7 @@ function generateBytecode(ast, options) {
    * @param {PEG.ast.Expr<T>} expression
    * @param {boolean} negative
    * @param {Context} context
+   * @returns {number[]}
    */
   function buildSimplePredicate(expression, negative, context) {
     const match = expression.match || 0;
@@ -446,6 +467,7 @@ function generateBytecode(ast, options) {
    * @param {PEG.ast.SemanticPredicate} node
    * @param {boolean} negative
    * @param {Context} context
+   * @returns {number[]}
    */
   function buildSemanticPredicate(node, negative, context) {
     const functionIndex = addFunctionConst(
@@ -471,8 +493,8 @@ function generateBytecode(ast, options) {
   }
 
   /**
-   *
    * @param {number[]} expressionCode
+   * @returns {number[]}
    */
   function buildAppendLoop(expressionCode) {
     return buildLoop(
@@ -591,7 +613,7 @@ function generateBytecode(ast, options) {
    * @param {number[]} expressionCode
    * @param {Context} context
    * @param {number} offset
-   * @returns
+   * @returns {number[]}
    */
   function buildRangeBody(
     delimiterNode,
@@ -640,7 +662,7 @@ function generateBytecode(ast, options) {
 
   /**
    * @param {PEG.compiler.visitor.NodeTypes} generators
-   * @returns
+   * @returns {PEG.compiler.visitor.AnyFunction}
    */
   function wrapGenerators(generators) {
     if (options && options.output === "source-and-map") {