Add more comments

Author: FifthTundraG

src/ts/buildings.ts

@@ -1,20 +1,19 @@
-import ClickerCookie from "./clickercookie.js";
 import { capitalize, commaify, clamp } from "./helper.js";
 import { Game } from "./main.js";
 import { SaveProvider } from "./saving.js";
 import { hideTooltip } from "./tooltip.js";
 
 export interface BuildingData {
-    /** Display name for your building. Should be capitialized. */
+    /** Display name for your building. Should be capitalized. */
     name: string;
-    /** *Plural* display name for your building. Should be capitialized. */
+    /** *Plural* display name for your building. Should be capitalized. */
     namePlural: string;
     quote: string;
-    /** Base upgrade cost for the building. */
+    /** Base upgrade cost for the building. Multiplied by {@link upgradeCostMultiplier} when building is bought. */
     upgradeCost: number;
     CPSGain: number;
     img?: string;
-    /** Default is 1.15 */
+    /** How much {@link upgradeCost} is multiplied by when building is bought. Default is 1.15 */
     upgradeCostMultiplier?: number;
     /** 
      * Returns a boolean based on whether the building may be unlocked.

src/ts/handler.ts

@@ -1,5 +1,19 @@
 import { StringifiedIdentifier } from "./helper.js";
 
+/**
+ * Handlers are the core feature for all content in the game. They store and manage different types of objects, such as buildings, upgrades, mods, and more.
+ *
+ * Each handler uses {@link Identifier}s to uniquely identify and retrieve objects (with the exception of {@link UniqueKeyHandler}s).
+ *
+ * Globally accessible handlers are stored in the {@link Handlers} class. These handlers are treated specially throughout the codebase to manage their respective content types. Generally, you will not create your own handlers if you are making a mod that does not drastically modify the game's core systems.
+ *
+ * Handlers can also be iterated over like so:
+ * ```ts
+ * for (const obj of handler) {
+ *     console.log(obj);
+ * }
+ * ```
+ */
 export class Handler<T> implements Iterable<T> {
     /** This stores the stringified Identifier as the key and then the values is obviously T. We store the identifier stringified because objects are never equal so we can't `get()` from the Map without using the same obj reference. */
     protected registered: Map<StringifiedIdentifier, T>;
@@ -123,6 +137,13 @@ export class UniqueKeyHandler<T> implements Iterable<T> {
     }
 }
 
+/**
+ * A unique identifier, usually for objects registered to {@link Handler}s.
+ *
+ * Identifiers are core to avoiding name collisions. If two mods were to register a building with the name `farm` then they would conflict with each other. The solution is to add a "namespace" such that these identifiers become `mod1:farm` and `mod2:farm`.
+ *
+ * If you are familiar with Minecraft mods these are functionally identical to how they are implemented there.
+ */
 export class Identifier {
     /**
      * Constructs a new {@link Identifier} from a stringified Identifier (from {@link Identifier.toString()}). If the string is not valid then a warning will be logged and `undefined` will be returned.

src/ts/helper.ts

@@ -49,7 +49,8 @@ export function commaify(toComma: number): string {
     return commaifyed;
 }
 
-/** Oftentimes, because JS is a pain in the butt hole, number such as 128.2 may instead be 128.2000000000013. This is not very friendly to look at. This makes that number better.
+/**
+ * Oftentimes, because CPUs are annoying, number such as 128.2 may instead be 128.2000000000013. This is not very friendly to look at. This makes that number better.
  * 
  * Historically, we would use a seperate object for numbers that would be impacted by this that would automatically apply the calculations in this function (variableView), but I prefer this method instead.
  * 

src/ts/mods.ts

@@ -1,7 +1,20 @@
 import { SaveProvider } from "./saving.js";
-import { ModHandler } from "./handlers.js";
+import { ModHandler, BackgroundHandler, CurrentlyClickedHandler } from "./handlers.js";
+import { Game } from "./main.js"
 
-type Kooh = "click" | "cps" | "loop" | "cps" | "personalization";
+/**
+ * Koohs ("hooks" spelled backwards) serve as events that mods can register functions to be called on. Register functions using {@link Mod.registerKooh}.
+ *
+ * These will all automatically be called by {@link Game} at the appropriate times. Usually, you should not need to call these manually.
+ *
+ * | Kooh            | When is it called? |
+ * | --------------- | ------------- |
+ * | click           | When the cookie is clicked ({@link Game.cookieClicked()}) |
+ * | cps             | When CPS is given ({@link Game.cookiesPerSecondUpdate()}) |
+ * | loop            | Called in game loop ({@link Game.gameLoop()}) |
+ * | personalization | Whenever a personalization option is changed ({@link BackgroundHandler.setBackground()}, {@link CurrentlyClickedHandler.setCurrentlyClicked()}) |
+ */
+type Kooh = "click" | "cps" | "loop" | "personalization";
 
 interface ModMetadata {
     name: string;
@@ -12,7 +25,7 @@ interface ModMetadata {
 }
 
 /**
- * Provides high-level abstractions for mod developers to work with
+ * Provides high-level abstractions for mod developers to work with. [Read the docs.](https://github.com/clickercookie/clickercookie.github.io/wiki/Modding)
  */
 export class Mod<T> implements SaveProvider<T> {
     // ------------------
@@ -44,7 +57,7 @@ export class Mod<T> implements SaveProvider<T> {
     /** Mod namespace used for saving */
     public readonly NAMESPACE: string;
 
-    constructor(namespace: string, metadata: ModMetadata={name: undefined, description: undefined, img: undefined}) { //? should namespace be a param?
+    constructor(namespace: string, metadata: ModMetadata={name: undefined, description: undefined, img: undefined}) {
         this.NAMESPACE = namespace;
 
         this.METADATA = {

src/ts/saving.ts

@@ -175,8 +175,11 @@ export interface SaveProvider<T> {
 }
 
 interface SaveDataHeader {
+    /** Current game version ({@link Game.VERSION}) */
     version: string;
+    /** Current game version branch ({@link Game.VERSION_BRANCH}) */
     versionBranch: VersionBranch;
+    /** Format for this save. Currently is always set to `4` but major updates to the spec will increment this. */
     format: number
 }
 

src/ts/upgrades.ts

@@ -2,7 +2,6 @@ import { Building } from "./buildings.js";
 import { clamp, commaify, countVisibleChildren, url } from "./helper.js";
 import { hideTooltip } from "./tooltip.js";
 import { Game } from "./main.js";
-import ClickerCookie from "./clickercookie.js";
 import { Handlers } from "./handlers.js";
 import { SaveProvider } from "./saving.js";