From 507d25455694dad818ecc3402a0f4dc4f3a67032 Mon Sep 17 00:00:00 2001
From: DJj123dj <80536295+DJj123dj@users.noreply.github.com>
Date: Mon, 27 Jan 2025 23:37:49 +0100
Subject: [PATCH] Added new API comments (part 8)

---
 src/core/api/modules/base.ts         | 10 ++---
 src/core/api/openticket/blacklist.ts | 16 +++++++
 src/core/api/openticket/option.ts    | 62 ++++++++++++++++++++++++++++
 3 files changed, 83 insertions(+), 5 deletions(-)

diff --git a/src/core/api/modules/base.ts b/src/core/api/modules/base.ts
index a77e90d..45c1e3e 100644
--- a/src/core/api/modules/base.ts
+++ b/src/core/api/modules/base.ts
@@ -51,11 +51,11 @@ export type ODInterfaceWithPartialProperty<Interface,Key extends keyof Interface
  * const id = new api.ODId("example%id?") //this is invalid
  */
 export class ODId {
-    /**The full value of this `ODId` as a `string` */
+    /**The full value of this `ODId` as a `string`. */
     value: string
-    /**The source of the id (part before `:`). For example `openticket` for all built-in ids! */
+    /**The source of the id (text before `:`). (e.g. `openticket` for all built-in ids) */
     source: string
-    /**The identifier of the id (part after `:`). */
+    /**The identifier of the id (text after `:`). */
     identifier: string
 
     constructor(id:ODValidId){
@@ -117,7 +117,7 @@ export class ODManagerChangeHelper {
             }
         }
     }
-    /****(❌ SYSTEM ONLY!!)** Set the callback executed when a value inside this class changes */
+    /****(❌ SYSTEM ONLY!!)** Set the callback executed when a value inside this class changes. */
     changed(callback:(() => void)|null){
         this.#change = callback
     }
@@ -170,7 +170,7 @@ export class ODManagerRedirectHelper {
  * There is an `id:ODId` property & also some events used in the manager.
  */
 export class ODManagerData extends ODManagerChangeHelper {
-    /**The id of this data */
+    /**The id of this data. */
     id: ODId
 
     constructor(id:ODValidId){
diff --git a/src/core/api/openticket/blacklist.ts b/src/core/api/openticket/blacklist.ts
index 4340139..448efc6 100644
--- a/src/core/api/openticket/blacklist.ts
+++ b/src/core/api/openticket/blacklist.ts
@@ -4,7 +4,15 @@
 import { ODManager, ODManagerData, ODValidId } from "../modules/base"
 import { ODDebugger } from "../modules/console"
 
+/**## ODBlacklist `class`
+ * This is an open ticket blacklisted user.
+ * 
+ * This class contains the id of the user this class belongs to & an optional reason for being blacklisted.
+ * 
+ * Create this class & add it to the `ODBlacklistManager` to blacklist someone!
+ */
 export class ODBlacklist extends ODManagerData {
+    /**The reason why this user got blacklisted. (optional) */
     #reason: string|null
 
     constructor(id:ODValidId,reason:string|null){
@@ -12,6 +20,7 @@ export class ODBlacklist extends ODManagerData {
         this.#reason = reason
     }
 
+    /**The reason why this user got blacklisted. (optional) */
     set reason(reason:string|null) {
         this.#reason = reason
         this._change()
@@ -21,6 +30,13 @@ export class ODBlacklist extends ODManagerData {
     }
 }
 
+/**## ODBlacklistManager `class`
+ * This is an open ticket blacklist manager.
+ * 
+ * This class manages all blacklisted users & their reason. Check if someone is blacklisted using their ID in the `exists()` method.
+ * 
+ * All `ODBlacklist`'s added, removed & edited in this list will be synced automatically with the database.
+ */
 export class ODBlacklistManager extends ODManager<ODBlacklist> {
     constructor(debug:ODDebugger){
         super(debug,"blacklist")
diff --git a/src/core/api/openticket/option.ts b/src/core/api/openticket/option.ts
index c75838f..a708083 100644
--- a/src/core/api/openticket/option.ts
+++ b/src/core/api/openticket/option.ts
@@ -9,8 +9,17 @@ import * as discord from "discord.js"
 import * as crypto from "crypto"
 import { OTRoleUpdateMode } from "./role"
 
+/**## ODOptionManager `class`
+ * This is an open ticket option manager.
+ * 
+ * This class manages all registered options in the bot. This also includes temporary options generated from tickets where the original option got deleted.
+ * 
+ * All option types including: tickets, websites & reaction roles are stored here.
+ */
 export class ODOptionManager extends ODManager<ODOption> {
+    /**A reference to the Open Ticket debugger. */
     #debug: ODDebugger
+    /**The option suffix manager used to generate channel suffixes for ticket names. */
     suffix: ODOptionSuffixManager
 
     constructor(debug:ODDebugger){
@@ -25,20 +34,41 @@ export class ODOptionManager extends ODManager<ODOption> {
     }
 }
 
+/**## ODOptionDataJson `interface`
+ * The JSON representatation from a single option property.
+ */
 export interface ODOptionDataJson {
+    /**The id of this property. */
     id:string,
+    /**The value of this property. */
     value:ODValidJsonType
 }
 
+/**## ODOptionDataJson `interface`
+ * The JSON representatation from a single option.
+ */
 export interface ODOptionJson {
+    /**The id of this option. */
     id:string,
+    /**The type of this option. (e.g. `openticket:ticket`, `openticket:website`, `openticket:role`) */
     type:string,
+    /**The version of Open Ticket used to create this option & store it in the database. */
     version:string,
+    /**The full list of properties/variables related to this option. */
     data:ODOptionDataJson[]
 }
 
+/**## ODOption `class`
+ * This is an open ticket option.
+ * 
+ * This class contains all data related to this option (parsed from the config).
+ * 
+ * It's recommended to use `ODTicketOption`, `ODWebsiteOption` or `ODRoleOption` instead!
+ */
 export class ODOption extends ODManager<ODOptionData<ODValidJsonType>> {
+    /**The id of this option. (from the config) */
     id:ODId
+    /**The type of this option. (e.g. `openticket:ticket`, `openticket:website`, `openticket:role`) */
     type: string
 
     constructor(id:ODValidId, type:string, data:ODOptionData<ODValidJsonType>[]){
@@ -50,6 +80,7 @@ export class ODOption extends ODManager<ODOptionData<ODValidJsonType>> {
         })
     }
 
+    /**Convert this option to a JSON object for storing this option in the database. */
     toJson(version:ODVersion): ODOptionJson {
         const data = this.getAll().map((data) => {
             return {
@@ -66,12 +97,21 @@ export class ODOption extends ODManager<ODOptionData<ODValidJsonType>> {
         }
     }
 
+    /**Create an option from a JSON object in the database. */
     static fromJson(json:ODOptionJson): ODOption {
         return new ODOption(json.id,json.type,json.data.map((data) => new ODOptionData(data.id,data.value)))
     }
 }
 
+/**## ODOptionData `class`
+ * This is open ticket option data.
+ * 
+ * This class contains a single property for a ticket option. (string, number, boolean, object, array, null)
+ * 
+ * When this property is edited, the database will be updated automatically.
+ */
 export class ODOptionData<DataType extends ODValidJsonType> extends ODManagerData {
+    /**The value of this property. */
     #value: DataType
 
     constructor(id:ODValidId, value:DataType){
@@ -79,6 +119,7 @@ export class ODOptionData<DataType extends ODValidJsonType> extends ODManagerDat
         this.#value = value
     }
 
+    /**The value of this property. */
     set value(value:DataType){
         this.#value = value
         this._change()
@@ -144,6 +185,13 @@ export interface ODTicketOptionIds {
     "openticket:limits-maximum-user":ODOptionData<number>
 }
 
+/**## ODTicketOption `class`
+ * This is an open ticket ticket option.
+ * 
+ * This class contains all data related to an Open Ticket ticket option (parsed from the config).
+ * 
+ * Use this option to create a new ticket!
+ */
 export class ODTicketOption extends ODOption {
     type: "openticket:ticket" = "openticket:ticket"
 
@@ -191,6 +239,13 @@ export interface ODWebsiteOptionIds {
     "openticket:url":ODOptionData<string>,
 }
 
+/**## ODWebsiteOption `class`
+ * This is an open ticket website option.
+ * 
+ * This class contains all data related to an Open Ticket website option (parsed from the config).
+ * 
+ * Use this option to create a button which links to a website!
+ */
 export class ODWebsiteOption extends ODOption {
     type: "openticket:website" = "openticket:website"
 
@@ -242,6 +297,13 @@ export interface ODRoleOptionIds {
     "openticket:add-on-join":ODOptionData<boolean>
 }
 
+/**## ODRoleOption `class`
+ * This is an open ticket role option.
+ * 
+ * This class contains all data related to an Open Ticket role option (parsed from the config).
+ * 
+ * Use this option to create a button for reaction roles!
+ */
 export class ODRoleOption extends ODOption {
     type: "openticket:role" = "openticket:role"