Swap from a named interface to anonymous interfaces i.e. object liter…

…al type parameters

javascript/devlog.md

@@ -201,9 +201,11 @@ We're now ready to add once again create an empty orphan branch;
 1. `git commit -m "Initial empty orphan" --allow-empty`
 1. `git push --set-upstream origin gh-pages-javascript`
 
-### [__namedParameters](https://typedoc.org/tags/param/#destructured-parameters)
-Apparently, specifying an input in the "destructured" format, like `({ n, P = 2n, a = 3n, b = 1n }: CollatzParameters)`, will lead to the name of the input being inferred by TypeDoc as `__namedParameters`. Any set of `@param` comments on a function that don't address this specific case will be ignored, but not necessarily in the order mentioned by the TypeDoc example.
+### "Destructured Parameters" + "Object Literal", or interfaces?
+Apparently, specifying an input in the ["destructured" format](https://typedoc.org/tags/param/#destructured-parameters) bound to an interface type, like `({ n, P = 2n, a = 3n, b = 1n }: CollatzParameters)` (where `CollatzParameters` is `{n:bigint, P?:bigint, a?:bigint, b?:bigint}`), will lead to the name of the input being inferred by TypeDoc as `__namedParameters`. Any set of `@param` comments on a function that don't address this specific case will be ignored, but not necessarily in the order mentioned by the TypeDoc example, or at least, not in the order I would assume, with the acknowledgement that I suffice the user acceptance testing role of "as a stupid user" per the KISS principle. So it's more probable the TypeDoc examples are fine, I'm just reading something extra that isn't there. So let's experiment a bit.
 
 For example, in [this case](https://github.com/Skenvy/Collatz/blob/559c27e2595ea4ad980582ae2a037f79091f4913/javascript/src/index.ts#L124-L137) where there are four `@param`'s, the output TypeDoc yielded was [this](https://github.com/Skenvy/Collatz/blob/gh-pages/javascript/functions/Function.html#L27-L31), which simply lists `__namedParameters` as the name of the only input. Which is where I have now just seen and realised I got my `@param`'s wrong, for accurately displaying the inputs in TypeDoc's output. So now, how can this be fixed?
 
 Well, testing this locally, there appear to be two ways to correctly yield a different name rather than `__namedParameters`. Either a single `@param`, for the one object input, _or_, a single `@param` that renames the top level object, along with the following lines obeying the [@param Object Literal](https://typedoc.org/tags/param/#object-literals) style, i.e. `* @param AnyNameHere - various options` followed by `* @param AnyNameHere.abc - property abc` will correctly yield renaming the `__namedParameters` to `AnyNameHere`, but I cannot get any way of rewriting the params underneath to yield their comments in the resulting site. Perhaps this is because it's not parsing the type of the object literal far enough to see the names of the parameters of the interface, and using the name of the interface instead of the "Object Literal" is a foot-gun? It would appear this is the case, because replacing the name of the interface with the "object literal" version of the interface, `{n:bigint, P?:bigint, a?:bigint, b?:bigint}`, allowed TypeDoc to yield the full documentation, as written on the function.
+
+I'm not sure if there's a more preferred style one way or the other whether to use named interfaces or not, it would certainly uphold the notion of minimising the amount of repeated code, or at least repeated comments. But using a named interface rather than an "anonymous interface" ("object literal" as the type parameter) means the doc comments won't appear for each function. I think given these, I'd rather get rid of the named interface and swap over to object literals for each function's singular input's type parameter.

javascript/lib/cjs/index.js

@@ -98,11 +98,11 @@ function assertSaneParameterisation(P, a, b) {
 exports.assertSaneParameterisation = assertSaneParameterisation;
 /**
  * Parameterised Collatz Function
- * @param AnyNameHere - various options
- * @param AnyNameHere.n - The value on which to perform the Collatz-esque function
- * @param AnyNameHere.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
- * @param AnyNameHere.a - Factor by which to multiply n. Default is 3.
- * @param AnyNameHere.b - Value to add to the scaled value of n. Default is 1.
+ * @param parameterisedInputs - Allows non-default (P,a,b)
+ * @param parameterisedInputs.n - The value on which to perform the Collatz-esque function
+ * @param parameterisedInputs.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
+ * @param parameterisedInputs.a - Factor by which to multiply n. Default is 3.
+ * @param parameterisedInputs.b - Value to add to the scaled value of n. Default is 1.
  * @returns the output of a single application of a Collatz-esque function.
  * @throws FailedSaneParameterCheck
  * Thrown if either P or a are 0.
@@ -114,10 +114,11 @@ function collatzFunction({ n, P = 2n, a = 3n, b = 1n }) {
 exports.collatzFunction = collatzFunction;
 /**
  * Parameterised Collatz Inverse Function
- * @param n - The value on which to perform the reverse Collatz function
- * @param P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
- * @param a - Factor by which to multiply n. Default is 3.
- * @param b - Value to add to the scaled value of n. Default is 1.
+ * @param parameterisedInputs - Allows non-default (P,a,b)
+ * @param parameterisedInputs.n - The value on which to perform the reverse Collatz function
+ * @param parameterisedInputs.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
+ * @param parameterisedInputs.a - Factor by which to multiply n. Default is 3.
+ * @param parameterisedInputs.b - Value to add to the scaled value of n. Default is 1.
  * @returns the output of a single application of a Collatz-esque reverse function.
  * @throws FailedSaneParameterCheck
  * Thrown if either P or a are 0.
@@ -252,11 +253,11 @@ exports.HailstoneSequence = HailstoneSequence;
  *     of iterations to reach a value less than the initial value).
  * @return (HailstoneSequence): A set of values that form the hailstone sequence.
  */
-function hailstoneSequence({ n, P = 2n, a = 3n, b = 1n }, maxTotalStoppingTime, totalStoppingTime) {
+function hailstoneSequence({ initialValue, P = 2n, a = 3n, b = 1n, maxTotalStoppingTime = 1000, totalStoppingTime = true }) {
     // Call out the function before any magic returns to trap bad values.
-    const throwaway = collatzFunction({ n: n, P: P, a: a, b: b });
+    const throwaway = collatzFunction({ n: initialValue, P: P, a: a, b: b });
     // Return the hailstone sequence.
-    return new HailstoneSequence(n, P, a, b, maxTotalStoppingTime, totalStoppingTime);
+    return new HailstoneSequence(initialValue, P, a, b, maxTotalStoppingTime, totalStoppingTime);
 }
 exports.hailstoneSequence = hailstoneSequence;
 exports.default = {

javascript/lib/cjs/types/index.d.ts

@@ -66,39 +66,13 @@ export declare enum SequenceState {
  * Thrown if either P or a are 0.
  */
 export declare function assertSaneParameterisation(P: bigint, a: bigint, b: bigint): void;
-/**
- * Parameterised inputs
- * @remarks
- * Allow (P,a,b) to be optional, keyword inputs.
- */
-export interface CollatzParameters {
-    /**
-     * The value on which to perform the operations; singular or iteratively.
-     */
-    n: bigint;
-    /**
-     * The modulus. Modulus used to devide n, iff n is equivalent to (0 mod P).
-     * @defaultValue 2n
-     */
-    P?: bigint;
-    /**
-     * The multiplicand. Factor by which to multiply n.
-     * @defaultValue 3n
-     */
-    a?: bigint;
-    /**
-     * The addend. Value to add to the scaled value of n.
-     * @defaultValue 1n
-     */
-    b?: bigint;
-}
 /**
  * Parameterised Collatz Function
- * @param AnyNameHere - various options
- * @param AnyNameHere.n - The value on which to perform the Collatz-esque function
- * @param AnyNameHere.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
- * @param AnyNameHere.a - Factor by which to multiply n. Default is 3.
- * @param AnyNameHere.b - Value to add to the scaled value of n. Default is 1.
+ * @param parameterisedInputs - Allows non-default (P,a,b)
+ * @param parameterisedInputs.n - The value on which to perform the Collatz-esque function
+ * @param parameterisedInputs.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
+ * @param parameterisedInputs.a - Factor by which to multiply n. Default is 3.
+ * @param parameterisedInputs.b - Value to add to the scaled value of n. Default is 1.
  * @returns the output of a single application of a Collatz-esque function.
  * @throws FailedSaneParameterCheck
  * Thrown if either P or a are 0.
@@ -111,15 +85,21 @@ export declare function collatzFunction({ n, P, a, b }: {
 }): bigint;
 /**
  * Parameterised Collatz Inverse Function
- * @param n - The value on which to perform the reverse Collatz function
- * @param P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
- * @param a - Factor by which to multiply n. Default is 3.
- * @param b - Value to add to the scaled value of n. Default is 1.
+ * @param parameterisedInputs - Allows non-default (P,a,b)
+ * @param parameterisedInputs.n - The value on which to perform the reverse Collatz function
+ * @param parameterisedInputs.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
+ * @param parameterisedInputs.a - Factor by which to multiply n. Default is 3.
+ * @param parameterisedInputs.b - Value to add to the scaled value of n. Default is 1.
  * @returns the output of a single application of a Collatz-esque reverse function.
  * @throws FailedSaneParameterCheck
  * Thrown if either P or a are 0.
  */
-export declare function reverseFunction({ n, P, a, b }: CollatzParameters): bigint[];
+export declare function reverseFunction({ n, P, a, b }: {
+    n: bigint;
+    P?: bigint;
+    a?: bigint;
+    b?: bigint;
+}): bigint[];
 /** Contains the results of computing a hailstone sequence. */
 export declare class HailstoneSequence {
     /** The set of values that comprise the hailstone sequence. */
@@ -168,7 +148,14 @@ export declare class HailstoneSequence {
  *     of iterations to reach a value less than the initial value).
  * @return (HailstoneSequence): A set of values that form the hailstone sequence.
  */
-export declare function hailstoneSequence({ n, P, a, b }: CollatzParameters, maxTotalStoppingTime: number, totalStoppingTime: boolean): HailstoneSequence;
+export declare function hailstoneSequence({ initialValue, P, a, b, maxTotalStoppingTime, totalStoppingTime }: {
+    initialValue: bigint;
+    P?: bigint;
+    a?: bigint;
+    b?: bigint;
+    maxTotalStoppingTime?: number;
+    totalStoppingTime?: boolean;
+}): HailstoneSequence;
 declare const _default: {
     collatzFunction: typeof collatzFunction;
     reverseFunction: typeof reverseFunction;

javascript/lib/esm/index.mjs

@@ -93,11 +93,11 @@ export function assertSaneParameterisation(P, a, b) {
 }
 /**
  * Parameterised Collatz Function
- * @param AnyNameHere - various options
- * @param AnyNameHere.n - The value on which to perform the Collatz-esque function
- * @param AnyNameHere.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
- * @param AnyNameHere.a - Factor by which to multiply n. Default is 3.
- * @param AnyNameHere.b - Value to add to the scaled value of n. Default is 1.
+ * @param parameterisedInputs - Allows non-default (P,a,b)
+ * @param parameterisedInputs.n - The value on which to perform the Collatz-esque function
+ * @param parameterisedInputs.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
+ * @param parameterisedInputs.a - Factor by which to multiply n. Default is 3.
+ * @param parameterisedInputs.b - Value to add to the scaled value of n. Default is 1.
  * @returns the output of a single application of a Collatz-esque function.
  * @throws FailedSaneParameterCheck
  * Thrown if either P or a are 0.
@@ -108,10 +108,11 @@ export function collatzFunction({ n, P = 2n, a = 3n, b = 1n }) {
 }
 /**
  * Parameterised Collatz Inverse Function
- * @param n - The value on which to perform the reverse Collatz function
- * @param P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
- * @param a - Factor by which to multiply n. Default is 3.
- * @param b - Value to add to the scaled value of n. Default is 1.
+ * @param parameterisedInputs - Allows non-default (P,a,b)
+ * @param parameterisedInputs.n - The value on which to perform the reverse Collatz function
+ * @param parameterisedInputs.P - Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.
+ * @param parameterisedInputs.a - Factor by which to multiply n. Default is 3.
+ * @param parameterisedInputs.b - Value to add to the scaled value of n. Default is 1.
  * @returns the output of a single application of a Collatz-esque reverse function.
  * @throws FailedSaneParameterCheck
  * Thrown if either P or a are 0.
@@ -258,11 +259,11 @@ export class HailstoneSequence {
  *     of iterations to reach a value less than the initial value).
  * @return (HailstoneSequence): A set of values that form the hailstone sequence.
  */
-export function hailstoneSequence({ n, P = 2n, a = 3n, b = 1n }, maxTotalStoppingTime, totalStoppingTime) {
+export function hailstoneSequence({ initialValue, P = 2n, a = 3n, b = 1n, maxTotalStoppingTime = 1000, totalStoppingTime = true }) {
     // Call out the function before any magic returns to trap bad values.
-    const throwaway = collatzFunction({ n: n, P: P, a: a, b: b });
+    const throwaway = collatzFunction({ n: initialValue, P: P, a: a, b: b });
     // Return the hailstone sequence.
-    return new HailstoneSequence(n, P, a, b, maxTotalStoppingTime, totalStoppingTime);
+    return new HailstoneSequence(initialValue, P, a, b, maxTotalStoppingTime, totalStoppingTime);
 }
 export default {
     collatzFunction,