Start adding documentation; fix ImgElem placement

package-lock.json

@@ -5923,6 +5923,27 @@
       "integrity": "sha1-hX95zjWVgMNA1DCBzGSJcNC7I04=",
       "dev": true
     },
+    "handlebars": {
+      "version": "4.7.6",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.6.tgz",
+      "integrity": "sha512-1f2BACcBfiwAfStCKZNrUCgqNZkGsAT7UM3kkYtXuLo0KnaVfjKOyf7PRzB6++aK9STyT1Pd2ZCPe3EGOXleXA==",
+      "dev": true,
+      "requires": {
+        "minimist": "^1.2.5",
+        "neo-async": "^2.6.0",
+        "source-map": "^0.6.1",
+        "uglify-js": "^3.1.4",
+        "wordwrap": "^1.0.0"
+      },
+      "dependencies": {
+        "source-map": {
+          "version": "0.6.1",
+          "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
+          "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+          "dev": true
+        }
+      }
+    },
     "har-schema": {
       "version": "2.0.0",
       "resolved": "https://registry.npm.taobao.org/har-schema/download/har-schema-2.0.0.tgz",
@@ -7321,6 +7342,12 @@
         "yallist": "^3.0.2"
       }
     },
+    "lunr": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.8.tgz",
+      "integrity": "sha512-oxMeX/Y35PNFuZoHp+jUj5OSEmLCaIH4KTFJh7a93cHBoFmpw2IoPs22VIz7vyO2YUnx2Tn9dzIwO2P/4quIRg==",
+      "dev": true
+    },
     "make-dir": {
       "version": "2.1.0",
       "resolved": "https://registry.npm.taobao.org/make-dir/download/make-dir-2.1.0.tgz?cache=0&sync_timestamp=1587567407163&other_urls=https%3A%2F%2Fregistry.npm.taobao.org%2Fmake-dir%2Fdownload%2Fmake-dir-2.1.0.tgz",
@@ -7346,6 +7373,12 @@
         "object-visit": "^1.0.0"
       }
     },
+    "marked": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-1.0.0.tgz",
+      "integrity": "sha512-Wo+L1pWTVibfrSr+TTtMuiMfNzmZWiOPeO7rZsQUY5bgsxpHesBEcIWJloWVTFnrMXnf/TL30eTFSGJddmQAng==",
+      "dev": true
+    },
     "md5.js": {
       "version": "1.3.5",
       "resolved": "https://registry.npm.taobao.org/md5.js/download/md5.js-1.3.5.tgz",
@@ -9343,6 +9376,15 @@
         "picomatch": "^2.2.1"
       }
     },
+    "rechoir": {
+      "version": "0.6.2",
+      "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz",
+      "integrity": "sha1-hSBLVNuoLVdC4oyWdW70OvUOM4Q=",
+      "dev": true,
+      "requires": {
+        "resolve": "^1.1.6"
+      }
+    },
     "regenerate": {
       "version": "1.4.1",
       "resolved": "https://registry.npm.taobao.org/regenerate/download/regenerate-1.4.1.tgz",
@@ -9931,6 +9973,17 @@
       "integrity": "sha1-Z6fQLHbJ2iT5nSCAj8re0ODgS+I=",
       "dev": true
     },
+    "shelljs": {
+      "version": "0.8.4",
+      "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.4.tgz",
+      "integrity": "sha512-7gk3UZ9kOfPLIAbslLzyWeGiEqx9e3rxwZM0KE6EL8GlGwjym9Mrlx5/p33bWTu9YG6vcS4MBxYZDHYr5lr8BQ==",
+      "dev": true,
+      "requires": {
+        "glob": "^7.0.0",
+        "interpret": "^1.0.0",
+        "rechoir": "^0.6.2"
+      }
+    },
     "signal-exit": {
       "version": "3.0.3",
       "resolved": "https://registry.npm.taobao.org/signal-exit/download/signal-exit-3.0.3.tgz?cache=0&sync_timestamp=1585253323149&other_urls=https%3A%2F%2Fregistry.npm.taobao.org%2Fsignal-exit%2Fdownload%2Fsignal-exit-3.0.3.tgz",
@@ -11007,6 +11060,52 @@
       "integrity": "sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=",
       "dev": true
     },
+    "typedoc": {
+      "version": "0.17.8",
+      "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.17.8.tgz",
+      "integrity": "sha512-/OyrHCJ8jtzu+QZ+771YaxQ9s4g5Z3XsQE3Ma7q+BL392xxBn4UMvvCdVnqKC2T/dz03/VXSLVKOP3lHmDdc/w==",
+      "dev": true,
+      "requires": {
+        "fs-extra": "^8.1.0",
+        "handlebars": "^4.7.6",
+        "highlight.js": "^10.0.0",
+        "lodash": "^4.17.15",
+        "lunr": "^2.3.8",
+        "marked": "1.0.0",
+        "minimatch": "^3.0.0",
+        "progress": "^2.0.3",
+        "shelljs": "^0.8.4",
+        "typedoc-default-themes": "^0.10.2"
+      },
+      "dependencies": {
+        "fs-extra": {
+          "version": "8.1.0",
+          "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz",
+          "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==",
+          "dev": true,
+          "requires": {
+            "graceful-fs": "^4.2.0",
+            "jsonfile": "^4.0.0",
+            "universalify": "^0.1.0"
+          }
+        },
+        "highlight.js": {
+          "version": "10.1.1",
+          "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.1.1.tgz",
+          "integrity": "sha512-b4L09127uVa+9vkMgPpdUQP78ickGbHEQTWeBrQFTJZ4/n2aihWOGS0ZoUqAwjVmfjhq/C76HRzkqwZhK4sBbg==",
+          "dev": true
+        }
+      }
+    },
+    "typedoc-default-themes": {
+      "version": "0.10.2",
+      "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.10.2.tgz",
+      "integrity": "sha512-zo09yRj+xwLFE3hyhJeVHWRSPuKEIAsFK5r2u47KL/HBKqpwdUSanoaz5L34IKiSATFrjG5ywmIu98hPVMfxZg==",
+      "dev": true,
+      "requires": {
+        "lunr": "^2.3.8"
+      }
+    },
     "typescript": {
       "version": "3.9.6",
       "resolved": "https://registry.npm.taobao.org/typescript/download/typescript-3.9.6.tgz",
@@ -12077,6 +12176,12 @@
       "integrity": "sha1-YQY29rH3A4kb00dxzLF/uTtHB5w=",
       "dev": true
     },
+    "wordwrap": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz",
+      "integrity": "sha1-J1hIEIkUVqQXHI0CJkQa3pDLyus=",
+      "dev": true
+    },
     "worker-farm": {
       "version": "1.7.0",
       "resolved": "https://registry.npm.taobao.org/worker-farm/download/worker-farm-1.7.0.tgz",

package.json

@@ -29,6 +29,7 @@
     "eslint-plugin-promise": "^4.2.1",
     "eslint-plugin-standard": "^4.0.0",
     "eslint-plugin-vue": "^6.2.2",
+    "typedoc": "^0.17.8",
     "typescript": "~3.9.3",
     "vue-template-compiler": "^2.6.11"
   }

src/game/combat.ts

@@ -77,6 +77,9 @@ export interface Effect {
   apply: (target: Creature) => LogEntry;
 }
 
+/**
+ * An instance of damage. Contains zero or more [[DamageInstance]] objects
+ */
 export class Damage {
   readonly damages: DamageInstance[]
 
@@ -119,11 +122,17 @@ export class Damage {
   }
 }
 
+/**
+ * Computes damage given the source and target of the damage.
+ */
 export interface DamageFormula {
   calc (user: Creature, target: Creature): Damage;
   describe (user: Creature, target: Creature): LogEntry;
 }
 
+/**
+ * Simply returns the damage it was given.
+ */
 export class ConstantDamageFormula implements DamageFormula {
   calc (user: Creature, target: Creature): Damage {
     return this.damage
@@ -138,6 +147,9 @@ export class ConstantDamageFormula implements DamageFormula {
   }
 }
 
+/**
+ * Randomly scales the damage it was given with a factor of (1-x) to (1+x)
+ */
 export class UniformRandomDamageFormula implements DamageFormula {
   calc (user: Creature, target: Creature): Damage {
     return this.damage.scale(Math.random() * this.variance * 2 - this.variance + 1)
@@ -152,10 +164,18 @@ export class UniformRandomDamageFormula implements DamageFormula {
   }
 }
 
+/**
+ * A Combatant has a list of possible actions to take.
+ *
+ * This may be merged with [[Actionable]]
+ */
 export interface Combatant {
     actions: Array<Action>;
 }
 
+/**
+ * An Action is anything that can be done by a [[Creature]] to a [[Creature]].
+ */
 export abstract class Action {
   allowed (user: Creature, target: Creature): boolean {
     return this.conditions.every(cond => cond.allowed(user, target))
@@ -174,6 +194,9 @@ export abstract class Action {
   }
 }
 
+/**
+ * A Condition describes whether or not something is permissible between two [[Creature]]s
+ */
 export interface Condition {
   allowed: (user: Creature, target: Creature) => boolean;
 }

src/game/interface.ts

@@ -1,10 +1,18 @@
 import { Stat, Vigor, StatDescs, VigorDescs, StatIcons, VigorIcons } from './combat'
 import tippy from 'tippy.js'
 
+/**
+ * A LogEntry is something that can produce zero or more HTMLElements
+ */
 export interface LogEntry {
   render: () => HTMLElement[];
 }
 
+/**
+ * Takes zero or more strings or [[LogEntry]] objects
+ *
+ * Produces a list of divs containing each string/object
+ */
 export class LogLines implements LogEntry {
   private parts: Array<string|LogEntry>
 
@@ -36,6 +44,9 @@ export enum FormatOpt {
   DamageInst = "damage-instance"
 }
 
+/**
+ * Wraps its LogEntry up in a span with the specified class
+ */
 export class FormatEntry implements LogEntry {
   constructor (private entry: LogEntry, private opt: FormatOpt) {
 
@@ -54,6 +65,11 @@ export class FormatEntry implements LogEntry {
   }
 }
 
+/**
+ * Wraps a string up in a span with the specified class
+ *
+ * This will probably be folded into FormatEntry soon
+ */
 export class FormatText implements LogEntry {
   constructor (private opt: FormatOpt, private line: string) {
 
@@ -67,6 +83,9 @@ export class FormatText implements LogEntry {
   }
 }
 
+/**
+ * Like [[LogLines]], but with spans instead of divs
+ */
 export class LogLine implements LogEntry {
   private parts: Array<string|LogEntry>
 
@@ -93,6 +112,9 @@ export class LogLine implements LogEntry {
   }
 }
 
+/**
+ * Produces a FontAwesome icon
+ */
 export class FAElem implements LogEntry {
   constructor (private name: string) {
 
@@ -105,6 +127,13 @@ export class FAElem implements LogEntry {
   }
 }
 
+/**
+ * Produces a representation of a creature's property, such as health or power
+ *
+ * Can be just the icon, or include a number as well
+ *
+ * A tooltip is attached to the symbol
+ */
 export class PropElem implements LogEntry {
   constructor (private prop: Stat | Vigor, private value: number|null = null) {
 
@@ -161,18 +190,26 @@ export class PropElem implements LogEntry {
   }
 }
 
+/**
+ * Produces an <img>
+ */
 export class ImgElem implements LogEntry {
   constructor (private url: string) {
 
   }
 
   render (): HTMLElement[] {
+    const div = document.createElement("div")
     const img = document.createElement("img")
     img.src = this.url
-    return [img]
+    div.appendChild(img)
+    return [div]
   }
 }
 
+/**
+ * Directly concatenates zero or more [[LogEntry]] objects, without wrapping them in anything
+ */
 export class CompositeLog implements LogEntry {
   entries: LogEntry[]