CONTRACT: codingcontract.attempt always returns a string (#231)

* ns.codingcontract always returns a string (reward on success, empty on fail), simplifying usage and documentation of function.
* Because of the above, return value still works when used as a boolean, as long as no direct equality comparison to true/false.
* Documentation expanded and examples added.
Co-authored by @quacksouls

dist/bitburner.d.ts

@@ -651,39 +651,42 @@ export declare interface BladeburnerCurAction {
     name: string;
 }
 
-/**
- * Options to affect the behavior of {@link CodingContract} attempt.
- * @public
- */
-export declare interface CodingAttemptOptions {
-    /** If truthy, then the function will return a string that states the contract’s reward when it is successfully solved. */
-    returnReward: boolean;
-}
-
 /**
  * Coding Contract API
  * @public
  */
 export declare interface CodingContract {
     /**
-     * Attempts a coding contract.
+     * Attempts a coding contract, returning a reward string on success or empty string on failure.
      * @remarks
      * RAM cost: 10 GB
      *
      * Attempts to solve the Coding Contract with the provided solution.
      *
-     * @param answer - Solution for the contract.
+     * @example
+     * ```js
+     * // NS1
+     * var reward = codingcontract.attempt(yourSolution, filename, hostname);
+     * if (reward) {
+     *   tprint("Contract solved successfully! Reward: " + reward)
+     * } else tprint("Failed to solve contract.")
+     * ```
+     * @example
+     * ```js
+     * // NS2
+     * const reward = codingcontract.attempt(yourSolution, filename, hostname);
+     * if (reward) {
+     *   ns.tprint(`Contract solved successfully! Reward: ${reward}`)
+     * } else ns.tprint("Failed to solve contract.")
+     * ```
+     *
+     * @param answer - Attempted solution for the contract.
      * @param filename - Filename of the contract.
-     * @param host - Hostname of the server containing the contract. Optional. Defaults to current server if not provided.
+     * @param host - Hostname of the server containing the contract. Optional. Defaults to current server if not
-     * @param opts - Optional parameters for configuring function behavior.
+     *   provided.
-     * @returns True if the solution was correct, false otherwise. If the returnReward option is configured, then the function will instead return a string. If the contract is successfully solved, the string will contain a description of the contract’s reward. Otherwise, it will be an empty string.
+     * @returns A reward description string on success, or an empty string on failure.
      */
-    attempt(
+    attempt(answer: string | number | any[], filename: string, host?: string): string;
-    answer: string | number | any[],
-    filename: string,
-    host?: string,
-    opts?: CodingAttemptOptions,
-    ): boolean | string;
 
     /**
      * Get the type of a coding contract.

markdown/bitburner.codingattemptoptions.md

@@ -1,20 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [bitburner](./bitburner.md) &gt; [CodingAttemptOptions](./bitburner.codingattemptoptions.md)
-
-## CodingAttemptOptions interface
-
-Options to affect the behavior of [CodingContract](./bitburner.codingcontract.md) attempt.
-
-<b>Signature:</b>
-
-```typescript
-interface CodingAttemptOptions 
-```
-
-## Properties
-
-|  Property | Type | Description |
-|  --- | --- | --- |
-|  [returnReward](./bitburner.codingattemptoptions.returnreward.md) | boolean | If truthy, then the function will return a string that states the contract’s reward when it is successfully solved. |
-

markdown/bitburner.codingattemptoptions.returnreward.md

@@ -1,13 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [bitburner](./bitburner.md) &gt; [CodingAttemptOptions](./bitburner.codingattemptoptions.md) &gt; [returnReward](./bitburner.codingattemptoptions.returnreward.md)
-
-## CodingAttemptOptions.returnReward property
-
-If truthy, then the function will return a string that states the contract’s reward when it is successfully solved.
-
-<b>Signature:</b>
-
-```typescript
-returnReward: boolean;
-```

markdown/bitburner.codingcontract.attempt.md

@@ -4,33 +4,27 @@
 
 ## CodingContract.attempt() method
 
-Attempts a coding contract.
+Attempts a coding contract, returning a reward string on success or empty string on failure.
 
 <b>Signature:</b>
 
 ```typescript
-attempt(
+attempt(answer: string | number | any[], filename: string, host?: string): string;
-    answer: string | number | any[],
-    filename: string,
-    host?: string,
-    opts?: CodingAttemptOptions,
-  ): boolean | string;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  answer | string \| number \| any\[\] | Solution for the contract. |
+|  answer | string \| number \| any\[\] | Attempted solution for the contract. |
 |  filename | string | Filename of the contract. |
 |  host | string | Hostname of the server containing the contract. Optional. Defaults to current server if not provided. |
-|  opts | [CodingAttemptOptions](./bitburner.codingattemptoptions.md) | Optional parameters for configuring function behavior. |
 
 <b>Returns:</b>
 
-boolean \| string
+string
 
-True if the solution was correct, false otherwise. If the returnReward option is configured, then the function will instead return a string. If the contract is successfully solved, the string will contain a description of the contract’s reward. Otherwise, it will be an empty string.
+A reward description string on success, or an empty string on failure.
 
 ## Remarks
 
@@ -38,3 +32,25 @@ RAM cost: 10 GB
 
 Attempts to solve the Coding Contract with the provided solution.
 
+## Example 1
+
+
+```js
+// NS1
+var reward = codingcontract.attempt(yourSolution, filename, hostname);
+if (reward) {
+  tprint("Contract solved successfully! Reward: " + reward)
+} else tprint("Failed to solve contract.")
+```
+
+## Example 2
+
+
+```js
+// NS2
+const reward = codingcontract.attempt(yourSolution, filename, hostname);
+if (reward) {
+  ns.tprint(`Contract solved successfully! Reward: ${reward}`)
+} else ns.tprint("Failed to solve contract.")
+```
+

markdown/bitburner.codingcontract.md

@@ -16,7 +16,7 @@ export interface CodingContract
 
 |  Method | Description |
 |  --- | --- |
-|  [attempt(answer, filename, host, opts)](./bitburner.codingcontract.attempt.md) | Attempts a coding contract. |
+|  [attempt(answer, filename, host)](./bitburner.codingcontract.attempt.md) | Attempts a coding contract, returning a reward string on success or empty string on failure. |
 |  [createDummyContract(type)](./bitburner.codingcontract.createdummycontract.md) | Generate a dummy contract. |
 |  [getContractType(filename, host)](./bitburner.codingcontract.getcontracttype.md) | Get the type of a coding contract. |
 |  [getContractTypes()](./bitburner.codingcontract.getcontracttypes.md) | List all contract types. |

markdown/bitburner.md

@@ -31,7 +31,6 @@
 |  [BitNodeMultipliers](./bitburner.bitnodemultipliers.md) | All multipliers affecting the difficulty of the current challenge. |
 |  [Bladeburner](./bitburner.bladeburner.md) | Bladeburner API |
 |  [BladeburnerCurAction](./bitburner.bladeburnercuraction.md) | Bladeburner current action. |
-|  [CodingAttemptOptions](./bitburner.codingattemptoptions.md) | Options to affect the behavior of [CodingContract](./bitburner.codingcontract.md) attempt. |
 |  [CodingContract](./bitburner.codingcontract.md) | Coding Contract API |
 |  [Corporation](./bitburner.corporation.md) | Corporation API |
 |  [CorporationInfo](./bitburner.corporationinfo.md) | General info about a corporation |

src/NetscriptFunctions/CodingContract.ts

@@ -1,8 +1,8 @@
 import { Player as player } from "../Player";
 import { CodingContract } from "../CodingContracts";
-import { CodingAttemptOptions, CodingContract as ICodingContract } from "../ScriptEditor/NetscriptDefinitions";
+import { CodingContract as ICodingContract } from "../ScriptEditor/NetscriptDefinitions";
 import { InternalAPI, NetscriptContext } from "../Netscript/APIWrapper";
-import { helpers, assertObjectType } from "../Netscript/NetscriptHelpers";
+import { helpers } from "../Netscript/NetscriptHelpers";
 import { codingContractTypesMetadata } from "../data/codingcontracttypes";
 import { generateDummyContract } from "../CodingContractGenerator";
 
@@ -18,18 +18,16 @@ export function NetscriptCodingContract(): InternalAPI<ICodingContract> {
   };
 
   return {
-    attempt: (ctx) => (answer, _filename, _hostname?, opts?) => {
+    attempt: (ctx) => (answer, _filename, _hostname?) => {
       const filename = helpers.string(ctx, "filename", _filename);
       const hostname = _hostname ? helpers.string(ctx, "hostname", _hostname) : ctx.workerScript.hostname;
       const contract = getCodingContract(ctx, hostname, filename);
 
-      const optsValidator: CodingAttemptOptions = { returnReward: true };
-      opts ??= optsValidator;
-      assertObjectType(ctx, "opts", opts, optsValidator);
       if (typeof answer !== "number" && typeof answer !== "string" && !Array.isArray(answer))
         throw new Error("The answer provided was not a number, string, or array");
 
       // Convert answer to string.
+      // Todo: better typing for contracts, don't do this weird string conversion of the player answer
       const answerStr = typeof answer === "string" ? answer : JSON.stringify(answer);
       const creward = contract.reward;
 
@@ -38,7 +36,7 @@ export function NetscriptCodingContract(): InternalAPI<ICodingContract> {
         const reward = player.gainCodingContractReward(creward, contract.getDifficulty());
         helpers.log(ctx, () => `Successfully completed Coding Contract '${filename}'. Reward: ${reward}`);
         serv.removeContract(filename);
-        return opts.returnReward ? reward : true;
+        return reward;
       } else {
         ++contract.tries;
         if (contract.tries >= contract.getMaxNumTries()) {
@@ -54,7 +52,7 @@ export function NetscriptCodingContract(): InternalAPI<ICodingContract> {
           );
         }
 
-        return opts.returnReward ? "" : false;
+        return "";
       }
     },
     getContractType: (ctx) => (_filename, _hostname?) => {

src/ScriptEditor/NetscriptDefinitions.d.ts

@@ -250,15 +250,6 @@ interface BasicHGWOptions {
   stock?: boolean;
 }
 
-/**
- * Options to affect the behavior of {@link CodingContract} attempt.
- * @public
- */
-interface CodingAttemptOptions {
-  /** If truthy, then the function will return a string that states the contract’s reward when it is successfully solved. */
-  returnReward: boolean;
-}
-
 /**
  * Return value of {@link Sleeve.getSleevePurchasableAugs | getSleevePurchasableAugs}
  * @public
@@ -3149,24 +3140,36 @@ export interface Bladeburner {
  */
 export interface CodingContract {
   /**
-   * Attempts a coding contract.
+   * Attempts a coding contract, returning a reward string on success or empty string on failure.
    * @remarks
    * RAM cost: 10 GB
    *
    * Attempts to solve the Coding Contract with the provided solution.
    *
-   * @param answer - Solution for the contract.
+   * @example
+   * ```js
+   * // NS1
+   * var reward = codingcontract.attempt(yourSolution, filename, hostname);
+   * if (reward) {
+   *   tprint("Contract solved successfully! Reward: " + reward)
+   * } else tprint("Failed to solve contract.")
+   * ```
+   * @example
+   * ```js
+   * // NS2
+   * const reward = codingcontract.attempt(yourSolution, filename, hostname);
+   * if (reward) {
+   *   ns.tprint(`Contract solved successfully! Reward: ${reward}`)
+   * } else ns.tprint("Failed to solve contract.")
+   * ```
+   *
+   * @param answer - Attempted solution for the contract.
    * @param filename - Filename of the contract.
-   * @param host - Hostname of the server containing the contract. Optional. Defaults to current server if not provided.
+   * @param host - Hostname of the server containing the contract. Optional. Defaults to current server if not
-   * @param opts - Optional parameters for configuring function behavior.
+   *   provided.
-   * @returns True if the solution was correct, false otherwise. If the returnReward option is configured, then the function will instead return a string. If the contract is successfully solved, the string will contain a description of the contract’s reward. Otherwise, it will be an empty string.
+   * @returns A reward description string on success, or an empty string on failure.
    */
-  attempt(
+  attempt(answer: string | number | any[], filename: string, host?: string): string;
-    answer: string | number | any[],
-    filename: string,
-    host?: string,
-    opts?: CodingAttemptOptions,
-  ): boolean | string;
 
   /**
    * Get the type of a coding contract.