Added new API comments (part 1)

Added new API comments (part 1)

src/core/api/modules/base.ts

@@ -45,7 +45,7 @@ export type ODInterfaceWithPartialProperty<Interface,Key extends keyof Interface
  * 
  * It can only contain the following characters: `a-z`, `A-Z`, `0-9`, `:`, `-` & `_`
  * 
- * You will use this class to assign a unique id when creating configs, databases, languages & more!
+ * You can use this class to assign a unique id when creating configs, databases, languages & more!
  * @example
  * const id = new api.ODId("openticket:test-id") //this is valid
  * const id = new api.ODId("example%id?") //this is invalid
@@ -102,7 +102,7 @@ export class ODId {
  * This is an open ticket manager change helper.
  * 
  * It is used to let the "onChange" event in the `ODManager` class work.
- * You will probably use this class when extending your own `ODManager`
+ * You can use this class when extending your own `ODManager`
  */
 export class ODManagerChangeHelper {
     #change: (() => void)|null = null
@@ -192,10 +192,11 @@ export type ODManagerAddCallback<DataType extends ODManagerData> = (data:DataTyp
 /**## ODManager `class`
  * This is an open ticket manager.
  * 
- * It can be used to store & manage different aspects of the bot!
+ * It can be used to store & manage classes based on their `ODId`.
- * You will probably to extend this class when creating your own classes & managers.
+ * It is somewhat the same as the default JS `Map()`.
+ * You can extend this class when creating your own classes & managers.
  * 
- * This class has many useful functions based on `ODId` (add, get, remove, getAll, getFiltered, exists)
+ * This class has many useful functions based on `ODId` (add, get, remove, getAll, getFiltered, exists, loopAll, ...)
  */
 export class ODManager<DataType extends ODManagerData> extends ODManagerChangeHelper {
     /**Alias to open ticket debugger. */

src/core/api/modules/checker.ts

@@ -19,7 +19,7 @@ export interface ODCheckerResult {
  * 
  * It manages all config checkers in the bot and allows plugins to access config checkers from open ticket & other plugins!
  * 
- * You will use this class to get/add a config checker (`ODChecker`) in your plugin!
+ * You can use this class to get/add a config checker (`ODChecker`) in your plugin!
  * @example
  * //get checker for ./config/general.json => ODChecker class
  * const testChecker = openticket.checkers.get("openticket:general")
@@ -99,7 +99,7 @@ export class ODCheckerManager extends ODManager<ODChecker> {
  * (e.g. The `messages.json` needs to access the `"id"` from `options.json`)
  * 
  * 
- * You will probably use this class when you create your own config checker!
+ * You can use this class when you create your own config checker implementation! (not required for using the built-in config checker)
  */
 export class ODCheckerStorage {
     /**This is the array that stores all the data. ❌ **(don't edit unless really needed!)***/
@@ -150,7 +150,7 @@ export class ODCheckerStorage {
  * It's responsible for rendering the config checker result in the console.
  * This class doesn't provide any components! You need to create them by extending this class
  * 
- * You will only use this class if you want to change how the config checker looks!
+ * You can use this class if you want to change how the config checker looks!
  */
 export class ODCheckerRenderer {
     /**Get all components */
@@ -174,7 +174,7 @@ export class ODCheckerRenderer {
  * It's used to store & manage the translation for each message from the config checker!
  * Most translations are stored by message id, but there are some exceptions like the additional text on the checker report.
  * 
- * You will use this class if you want to translate your config checker messages! **This is optional & isn't required for the checker to work!**
+ * You can use this class if you want to translate your config checker messages! **This is optional & isn't required for the checker to work!**
  */
 export class ODCheckerTranslationRegister {
     /**This is the array that stores all the data. ❌ **(don't edit unless really needed!)***/
@@ -298,7 +298,7 @@ export type ODCheckerLocationTrace = (string|number)[]
  * It checks a specific config file for invalid/missing configurations. This data can then be used to show to the user what's wrong!
  * You can check for example if a string is longer/shorter than a certain amount of characters & more!
  * 
- * You will use this class when you create your own custom config file & you want to check it for syntax errors.
+ * You can use this class when you create your own custom config file & you want to check it for syntax errors.
  * @example
  * //create a new checker with id "test" => ./config/test.json
  * const testConfig = new api.ODConfig("test","test.json")
@@ -410,7 +410,7 @@ export interface ODCheckerStructureOptions {
  * This class will check for a single variable in a config file, customise it in the settings!
  * If you want prebuilt checkers (for strings, booleans, numbers, ...), check the other `ODCheckerStructure`'s!
  * 
- * You will almost never use this class! It's better if you extend on another `ODConfigCheckerStructure`!
+ * **Not recommended to use!** It's recommended to extend from another `ODConfigCheckerStructure` class!
  */
 export class ODCheckerStructure {
     /**The id of this checker structure */

src/core/api/modules/code.ts

@@ -8,11 +8,14 @@ import { ODDebugger } from "./console"
 /**## ODCode `class`
  * This is an open ticket code runner.
  * 
- * It is just a function that will run just before the bot has started completely! 
+ * Using this, you're able to execute a function just before the startup screen. (90% of the code is already loaded)
- * This can be used for code that needs to run at startup, but isn't really time dependent.
+ * You can also specify a priority to change the execution order.
- * 
+ * In Open Ticket, this is used for the following processes:
- * - It has an `id` for identification of the function
+ * - Autoclose/delete
- * - A `priority` to know when to execute this function (related to others)
+ * - Database syncronisation (with tickets, stats & used options)
+ * - Panel auto-update
+ * - Database Garbage Collection (removing tickets that don't exist anymore)
+ * - And more!
  */
 export class ODCode extends ODManagerData {
     /**The priority of this code */
@@ -32,14 +35,14 @@ export class ODCode extends ODManagerData {
  * 
  * It manages & executes `ODCode`'s in the correct order.
  * 
- * You will probably register a function/code in this class for something that doesn't really need to be timed.
+ * Use this to register a function/code which executes just before the startup screen. (90% is already loaded)
  */
 export class ODCodeManager extends ODManager<ODCode> {
     constructor(debug:ODDebugger){
         super(debug,"code")
     }
     
-    /**Execute all functions or code. */
+    /**Execute all `ODCode` functions in order of their priority (high to low). */
     async execute(){
         const derefArray = [...this.getAll()]
         const workers = derefArray.sort((a,b) => b.priority-a.priority)

src/core/api/modules/config.ts

@@ -9,9 +9,9 @@ import fs from "fs"
 /**## ODConfigManager `class`
  * This is an open ticket config manager.
  * 
- * It manages all config files in the bot and allows plugins to access config files from open ticket & other plugins!
+ * It manages all config files in the bot and allows plugins to access config files from Open Ticket & other plugins!
  * 
- * You will use this class to get/add a config file (`ODConfig`) in your plugin!
+ * You can use this class to get/change/add a config file (`ODConfig`) in your plugin!
  */
 export class ODConfigManager extends ODManager<ODConfig> {
     constructor(debug:ODDebugger){
@@ -33,7 +33,7 @@ export class ODConfigManager extends ODManager<ODConfig> {
  * This is an open ticket config helper.
  * This class doesn't do anything at all, it just gives a template & basic methods for a config. Use `ODJsonConfig` instead!
  * 
- * You will only use this class if you want to create your own config implementation (e.g. `yml`, `xml`,...)!
+ * You can use this class if you want to create your own config implementation (e.g. `yml`, `xml`,...)!
  */
 export class ODConfig extends ODManagerData {
     /**The name of the file with extension. */
@@ -55,8 +55,8 @@ export class ODConfig extends ODManagerData {
 }
 
 /**## ODJsonConfig `class`
- * This is an open ticket config helper.
+ * This is an open ticket JSON config.
- * You will use this class to get & edit variables from the config files or to create your own config!
+ * You can use this class to get & edit variables from the config files or to create your own JSON config!
  * @example
  * //create a config from: ./config/test.json with the id "some-config"
  * const config = new api.ODJsonConfig("some-config","test.json")

src/core/api/modules/console.ts

@@ -583,7 +583,7 @@ export class ODLiveStatusUrlSource extends ODLiveStatusSource {
  * 
  * It manages all LiveStatus sources and has the renderer for all LiveStatus messages.
  * 
- * You will probably use this to customise or add stuff to the LiveStatus system.
+ * You can use this to customise or add stuff to the LiveStatus system.
  * Access it in the global `openticket.startscreen.livestatus` variable!
  */
 export class ODLiveStatusManager extends ODManager<ODLiveStatusSource> {

src/core/api/modules/database.ts

@@ -12,7 +12,7 @@ import * as fjs from "formatted-json-stringify"
  * 
  * It manages all databases in the bot and allows to permanently store data from the bot!
  * 
- * You will use this class to get/add a database (`ODDatabase`) in your plugin!
+ * You can use this class to get/add a database (`ODDatabase`) in your plugin!
  */
 export class ODDatabaseManager extends ODManager<ODDatabase> {
     constructor(debug:ODDebugger){
@@ -35,7 +35,7 @@ export class ODDatabaseManager extends ODManager<ODDatabase> {
  * This is an open ticket database template.
  * This class doesn't do anything at all, it just gives a template & basic methods for a database. Use `ODJsonDatabase` instead!
  * 
- * You will only use this class if you want to create your own database implementation (e.g. `mongodb`, `mysql`,...)!
+ * You can use this class if you want to create your own database implementation (e.g. `mongodb`, `mysql`,...)!
  */
 export class ODDatabase extends ODManagerData {
     /**The name of the file with extension. */
@@ -83,7 +83,7 @@ export type ODJsonDatabaseStructure = {category:string, key:string, value:ODVali
  * It stores data in a `json` file as a large `Array` using the `category`, `key`, `value` strategy.
  * You can store the following types: `string`, `number`, `boolean`, `array`, `object` & `null`!
  * 
- * You will use this class if you want to create your own database or use an existing one!
+ * You can use this class if you want to add your own database or to use an existing one!
  */
 export class ODJsonDatabase extends ODDatabase {
     constructor(id:ODValidId, file:string, customPath?:string){

src/core/api/modules/event.ts

@@ -75,8 +75,8 @@ export class ODEvent extends ODManagerData {
  * 
  * This class is made to manage all events in the bot. You can compare it with the built-in node.js `EventEmitter`
  * 
- * You will probably not create this class yourself, but use it globaly instead!
+ * It's not recommended to create this class yourself. Plugin events should be registered in their `plugin.json` file instead.
- * Check out the `openticket.events` class!
+ * All events are available in the `openticket.events` global!
  */
 export class ODEventManager extends ODManager<ODEvent> {
     /**Reference to the Open Ticket debugger */

src/core/api/modules/language.ts

@@ -6,17 +6,36 @@ import nodepath from "path"
 import { ODDebugger } from "./console"
 import fs from "fs"
 
+/**## ODLanguageMetadata `interface`
+ * This interface contains all metadata available in the language files.
+ */
 export interface ODLanguageMetadata {
+    /**The version of Open Ticket this translation is made for. */
     otversion:string,
+    /**The name of the language in english (with capital letter). */
     language:string,
+    /**A list of translators (discord/github username) who've contributed to this language. */
     translators:string[],
+    /**The last date that this translation has been modified (format: DD/MM/YYYY) */
     lastedited:string,
+    /**When `true`, the translator made use of some sort of automation while creating the translation. (e.g. ChatGPT, Google Translate, DeepL, ...) */
     automated:boolean
 }
 
+/**## ODLanguageManager `class`
+ * This is an open ticket language manager.
+ * 
+ * It manages all languages in the bot and manages translation for you!
+ * Get a translation via the `getTranslation()` or `getTranslationWithParams()` methods.
+ * 
+ * Add new languages using the `ODlanguage` class in your plugin!
+ */
 export class ODLanguageManager extends ODManager<ODLanguage> {
+    /**The currently selected language. */
     current: ODLanguage|null = null
+    /**The currently selected backup language. (used when translation missing in current language) */
     backup: ODLanguage|null = null
+    /**An alias to Open Ticket debugger. */
     #debug: ODDebugger
     
     constructor(debug:ODDebugger, presets:boolean){
@@ -27,6 +46,7 @@ export class ODLanguageManager extends ODManager<ODLanguage> {
         this.#debug = debug
     }
 
+    /**Set the current language by providing the ID of a language which is registered in this manager. */
     setCurrentLanguage(id:ODValidId){
         this.current = this.get(id)
         const languageId = this.current?.id.value ?? "<unknown-id>"
@@ -36,9 +56,11 @@ export class ODLanguageManager extends ODManager<ODLanguage> {
             {key:"automated",value:languageAutomated},
         ])
     }
+    /**Get the current language (same as `this.current`) */
     getCurrentLanguage(){
         return (this.current) ? this.current : null
     }
+    /**Set the backup language by providing the ID of a language which is registered in this manager. */
     setBackupLanguage(id:ODValidId){
         this.backup = this.get(id)
         const languageId = this.backup?.id.value ?? "<unknown-id>"
@@ -48,16 +70,20 @@ export class ODLanguageManager extends ODManager<ODLanguage> {
             {key:"automated",value:languageAutomated},
         ])
     }
+    /**Get the backup language (same as `this.backup`) */
     getBackupLanguage(){
         return (this.backup) ? this.backup : null
     }
+    /**Get the metadata of the current/backup language. */
     getLanguageMetadata(frombackup?:boolean): ODLanguageMetadata|null {
         if (frombackup) return (this.backup) ? this.backup.metadata : null
         return (this.current) ? this.current.metadata : null
     }
+    /**Get the ID (string) of the current language. (Not backup language) */
     getCurrentLanguageId(){
         return (this.current) ? this.current.id.value : ""
     }
+    /**Get a translation string by JSON location. (e.g. `"checker.system.typeError"`) */
     getTranslation(id:string): string|null {
         if (!this.current) return this.#getBackupTranslation(id)
         
@@ -75,7 +101,7 @@ export class ODLanguageManager extends ODManager<ODLanguage> {
         if (typeof result == "string") return result
         else return this.#getBackupTranslation(id)
     }
-
+    /**Get a backup  translation string by JSON location. (system only) */
     #getBackupTranslation(id:string): string|null {
         if (!this.backup) return null
 
@@ -93,7 +119,7 @@ export class ODLanguageManager extends ODManager<ODLanguage> {
         if (typeof result == "string") return result
         else return null
     }
-
+    /**Get a backup translation string by JSON location and replace `{0}`,`{1}`,`{2}`,... with the provided parameters. */
     getTranslationWithParams(id:string, params:string[]): string|null {
         let translation = this.getTranslation(id)
         if (!translation) return translation

src/core/api/modules/post.ts

@@ -11,7 +11,7 @@ import * as discord from "discord.js"
  * 
  * It manages `ODPosts`'s for you.
  * 
- * You will probably use this to get the logs channel of the bot (or some other static channel/category).
+ * You can use this to get the logs channel of the bot (or some other static channel/category).
  */
 export class ODPostManager extends ODManager<ODPost<discord.GuildBasedChannel>> {
     /**A reference to the main server of the bot */

src/core/api/modules/worker.ts

@@ -36,7 +36,7 @@ export class ODWorker<Instance, Source extends string, Params> extends ODManager
  * 
  * It manages & executes `ODWorker`'s in the correct order.
  * 
- * You will probably register a custom worker in this class to create a message or button.
+ * You can register a custom worker in this class to create a message or button.
  */
 export class ODWorkerManager<Instance, Source extends string, Params> extends ODManager<ODWorker<Instance,Source,Params>> {
     /**The order of execution for workers inside this manager. */