Merge pull request #19 from Kruhlmann/typescript

Did some cleanup

package.json

@@ -1,6 +1,6 @@
 {
   "name": "classicdb_bot",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "A discord bot, which makes it easy to link items from the WoW Classic database on classicdb.ch",
   "main": "src/main.js",
   "scripts": {

src/io.ts

@@ -11,7 +11,7 @@ import * as config from "../config.json";
  * Handles errors. During production will alert sentry about the occurrence of
  * the error. Otherwise it will be appended to the log file.
  *
- * @param {Error | string} error - Error to report.
+ * @param error - Error to report.
  */
 export function handle_exception(error: Error | string) {
     if (typeof error === "string") {
@@ -25,6 +25,11 @@ export function handle_exception(error: Error | string) {
     }
 }
 
+/**
+ * Logs a message.
+ *
+ * @param message - Message to log.
+ */
 export function log(message: string) {
     /* tslint:disable-next-line:no-console */
     console.log(message);

src/lib.ts

@@ -7,7 +7,9 @@
 import { DMChannel, GroupDMChannel, TextChannel } from "discord.js";
 import * as request from "request-promise";
 import * as config from "../config.json";
-import { ChannelIdentity, CharacterClass, ItemQuality } from "./typings/types.js";
+import { ChannelIdentity,
+         CharacterClass,
+         ItemQuality } from "./typings/types.js";
 
 /**
  * Returns the URL of an icon based on it's name in the JavaScript.
@@ -21,6 +23,12 @@ export function get_large_icon_url(icon_name: string) {
     return `${config.host}/images/icons/large/${icon_name}.jpg`;
 }
 
+/**
+ * Converts a datbase CSS element class into a ItemQuality.
+ *
+ * @param class_name - CSS class.
+ * @returns - Corresponding ItemQuality.
+ */
 export function css_class_to_item_quality(class_name: string): ItemQuality {
     switch (class_name) {
         case "q1": return ItemQuality.POOR;
@@ -35,6 +43,12 @@ export function css_class_to_item_quality(class_name: string): ItemQuality {
     }
 }
 
+/**
+ * Converts a datbase CSS element class into a CharacterClass.
+ *
+ * @param class_name - CSS class.
+ * @returns - Corresponding CharacterClass.
+ */
 export function css_class_to_player_class(class_name: string): CharacterClass {
     switch (class_name) {
         case "c1": return CharacterClass.WARRIOR;
@@ -66,6 +80,13 @@ export function find_first_item_index(item_details: number[][]): number {
     return -1;
 }
 
+/**
+ * Finds the string representation of the type of a discord message channel.
+ *
+ * @param channel - Discord channel object.
+ * @param author - Author of message in the channel.
+ * @returns - ChannelIdentity object withhannel and guild name as strings.
+ */
 export function get_channel_identity(channel: TextChannel
                                             | GroupDMChannel
                                             | DMChannel,
@@ -91,13 +112,13 @@ export function get_channel_identity(channel: TextChannel
  * Finds the thumbnail of either an item or a spell.
  *
  * @async
- * @param {string} id - Spell/item id.
- * @param {boolean} [spell=false] - If true will look for a spell, else looks
+ * @param id - Spell/item id.
+ * @param spell - If true will look for a spell, else looks
  * for an item.
  */
-export async function fetch_thumbnail(id: string, spell = false): Promise <string> {
+export async function fetch_thumbnail(id: string,
+                                      spell = false): Promise <string> {
     const url = `${config.host}/?${spell ? "spell" : "item"}=${id}`;
-    console.log(url)
     const html = await request(url);
     // Find the JavaScript line with "Icon.create" in from which the item
     // identifier can be extracted.
@@ -113,7 +134,7 @@ export async function fetch_thumbnail(id: string, spell = false): Promise <strin
 }
 
 /**
- * Test whether a string is a representation of a numerical integet.
+ * Tests whether a string is a representation of a numerical integet.
  *
  * @param {string} str - String to test.
  * @returns {boolean} - True if string represents a numerical integer.

src/parser/effect.ts

@@ -13,6 +13,12 @@ import { fetch_thumbnail } from "../lib.js";
 
 export class Effect {
 
+    /**
+     * Generates all effects from a database item tooltip element.
+     *
+     * @param table - Tooltip HTML as a Cheerio element.
+     * @returns - Generated effects.
+     */
     public static from_item_table(table: Cheerio): Promise<Effect[]> {
         const $ = cheerio.load(table.html());
         const effects: Array<Promise<Effect>> = [];
@@ -25,6 +31,14 @@ export class Effect {
         return Promise.all(effects);
     }
 
+    /**
+     * Generates an Effect from the HTML content of an effect database webpage.
+     *
+     * @async
+     * @param id - Database effect id.
+     * @param html - Database webpage HTML content.
+     * @param trigger - Effect trigger.
+     */
     public static async from_effect_html(id: string,
                                          html: string,
                                          trigger: string): Promise<Effect> {
@@ -66,6 +80,14 @@ export class Effect {
         return new Effect(id, name, `${config.host}/?item=${id}`, description, thumbnail, trigger, is_misc, cast_time, range);
     }
 
+    /**
+     * Generates an item based on an effect id and a trigger.
+     *
+     * @async
+     * @param id - Database effect id.
+     * @param trigger - Effect trigger.
+     * @returns - Generated effect.
+     */
     public static async from_id(id: string, trigger: string): Promise<Effect> {
         const url = `${config.host}/?spell=${id}`;
         const html = await request(url);
@@ -82,6 +104,25 @@ export class Effect {
     public cast_time: string;
     public range: string;
 
+    /**
+     * Constructor
+     *
+     * @constructor
+     * @param id - Database effect id.
+     * @param name - Effect name.
+     * @param href - Database website link.
+     * @param description - Full effect description.
+     * @param thumbnail_href - Link to effect thumbnail.
+     * @param trigger_name - Type of trigger associated with the effect. This
+     * can be different for the same effect as it is specified on a pre-item
+     * basis.
+     * @param is_misc - Whether the effect is a miscellaneous effect.
+     * Miscellaneous effects are represented by the cog thumbnail and are
+     * typically smaller effects that do not need their own RichEmbed message to
+     * be displayed with an item.
+     * @param cast_time - Cast time of effect.
+     * @param range - The maximum range of the effect.
+     */
     public constructor(id: string,
                        name: string,
                        href: string,
@@ -102,13 +143,26 @@ export class Effect {
         this.range = range;
     }
 
+    /**
+     * Generates a summary of the effect based on whether it's a miscellaneous
+     * effect. Used inside the item tooltip stats region.
+     *
+     * @returns Short effect summary.
+     */
     public as_short_tooltip(): string {
         return this.is_misc
             ? `${this.trigger_name}: ${this.description}`
             : `${this.trigger_name}: ${this.name}`;
     }
 
-    public build_message_description() {
+    /**
+     * Generates the description part of a RichEmbed message for the effect.
+     * This includes the name, cast time, maximum range and full effect
+     * description.
+     *
+     * @returns Generated RichEmbed description.
+     */
+    public build_message_description(): string {
         const cast_time = this.cast_time
             ? this.cast_time === "Instant"
                 ? `**${this.cast_time}**\n`

src/parser/item.ts

@@ -8,7 +8,11 @@ import * as cheerio from "cheerio";
 import { RichEmbed } from "discord.js";
 import * as request from "request-promise";
 import * as config from "../../config.json";
-import { discord_href, discord_icon, favicon_path, github_icon, html_tag_regex, misc_icon } from "../consts.js";
+import { discord_href,
+         discord_icon,
+         favicon_path,
+         html_tag_regex,
+         misc_icon } from "../consts.js";
 import { css_class_to_item_quality,
          css_class_to_player_class,
          fetch_thumbnail } from "../lib";
@@ -22,6 +26,7 @@ export class Item {
     /**
      * Generates an item based on a tooltip table from the database website.
      *
+     * @async
      * @param id - Database item id.
      * @param href - Link to item.
      * @param effects - List of item effects.
@@ -149,6 +154,7 @@ export class Item {
     /**
      * Generates an item based on the database website tooltip html.
      *
+     * @async
      * @param id - Database item id.
      * @param href - Item link.
      * @param html - Tooltip HTML.
@@ -161,7 +167,7 @@ export class Item {
         const tables = $("div.tooltip > table tbody tr td").children("table");
 
         // First table contains raw stats of the item. Second table contains
-        // spells, set bonuses and flavor text.
+        // effects, set bonuses and flavor text.
         const stat_table = tables.get(0);
         const misc_table = tables.get(1);
         const effects = Effect.from_item_table($(misc_table));
@@ -172,6 +178,7 @@ export class Item {
     /**
      * Builds an item from a database item id.
      *
+     * @async
      * @param id - Database item id.
      * @returns - Generated item.
      */
@@ -277,7 +284,7 @@ export class Item {
      * attributes in accordance with the standard tooltip layout. Should be used
      * for adding a description field to a discord RichEmbed message.
      *
-     * @returns {string} - Item tooltip.
+     * @returns - Item tooltip.
      */
     public build_message_description(): string {
         // Equipment type and slot.
@@ -286,7 +293,7 @@ export class Item {
         // a "Sword" of equipment_type "Two-hand" becomes "Two-handed Sword".
         const equipment_formatted = this.equipment_slot && this.equipment_type
             ? `${equipment_str(this.equipment_slot, this.equipment_type)}\n`
-            : this.equipment_slot ? `${this.equipment_slot}\n` : ""; 
+            : this.equipment_slot ? `${this.equipment_slot}\n` : "";
 
         // Damage.
         const dmg_formatted = this.damage_range && this.swing_speed && this.dps
@@ -340,7 +347,7 @@ export class Item {
             // however still be a short entry with the effect trigger and name
             // present in the description, which is generated by the effect
             // function `as_short_tooltip`.
-            // Non-complex effects such as added hit % or spellpower will not
+            // Non-complex effects such as added hit % or spell power will not
             // need their own message and are kept in full.
             ? `\n${this.effects.map((e) => {
                     return `[${e.as_short_tooltip()}](${e.href})`;
@@ -364,7 +371,8 @@ export class Item {
      * Constrcuts a list of discord RichEmbed messages, which can be sent to a
      * channel to represent the item.
      *
-     * @returns {RichEmbed[]} - List of messages.
+     * @async
+     * @returns - List of messages.
      */
     public async build_messages(): Promise<RichEmbed[]> {
         const effects = Promise.all(this.effects.filter((e) => {

src/parser/itemset.ts

@@ -1,22 +1,23 @@
 import * as cheerio from "cheerio";
 import * as request from "request-promise";
 import * as config from "../../config.json";
-import { handle_exception } from "../io.js";
-import { SetBonus } from "../typings/types.js";
-import { Effect } from "./effect";
-import { Item } from "./item";
-
 /**
  * @fileoverview Class definition for ItemSet.
  * @author Andreask Kruhlmann
  * @since 1.2.0
  */
 
+import { handle_exception } from "../io.js";
+import { SetBonus } from "../typings/types.js";
+import { Effect } from "./effect";
+import { Item } from "./item";
+
 export class ItemSet {
 
     /**
      * Generates an item set based on a database website url.
      *
+     * @async
      * @param id - Database itemset id.
      * @returns - Generated item set.
      */
@@ -27,6 +28,7 @@ export class ItemSet {
     /**
      * Generates an item set based on a database website url.
      *
+     * @async
      * @param url - URL of itemset.
      * @returns - Generated item set.
      */