From 061523578085b5578320642769d44fd1424a5fcc Mon Sep 17 00:00:00 2001 From: JasperAtSchool Date: Thu, 9 Jan 2025 17:48:50 +0100 Subject: [PATCH] Added new API comments (part 1) --- src/core/api/modules/base.ts | 11 ++++++----- src/core/api/modules/checker.ts | 12 ++++++------ src/core/api/modules/code.ts | 17 ++++++++++------- src/core/api/modules/config.ts | 10 +++++----- src/core/api/modules/console.ts | 2 +- src/core/api/modules/database.ts | 6 +++--- src/core/api/modules/event.ts | 4 ++-- src/core/api/modules/language.ts | 30 ++++++++++++++++++++++++++++-- src/core/api/modules/post.ts | 2 +- src/core/api/modules/worker.ts | 2 +- 10 files changed, 63 insertions(+), 33 deletions(-) diff --git a/src/core/api/modules/base.ts b/src/core/api/modules/base.ts index b422fce..a77e90d 100644 --- a/src/core/api/modules/base.ts +++ b/src/core/api/modules/base.ts @@ -45,7 +45,7 @@ export type ODInterfaceWithPartialProperty void)|null = null @@ -192,10 +192,11 @@ export type ODManagerAddCallback = (data:DataTyp /**## ODManager `class` * This is an open ticket manager. * - * It can be used to store & manage different aspects of the bot! - * You will probably to extend this class when creating your own classes & managers. + * It can be used to store & manage classes based on their `ODId`. + * 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 extends ODManagerChangeHelper { /**Alias to open ticket debugger. */ diff --git a/src/core/api/modules/checker.ts b/src/core/api/modules/checker.ts index 77bdc6f..01cee77 100644 --- a/src/core/api/modules/checker.ts +++ b/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 { * (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 */ diff --git a/src/core/api/modules/code.ts b/src/core/api/modules/code.ts index 08cb395..8d1885c 100644 --- a/src/core/api/modules/code.ts +++ b/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! - * This can be used for code that needs to run at startup, but isn't really time dependent. - * - * - It has an `id` for identification of the function - * - A `priority` to know when to execute this function (related to others) + * Using this, you're able to execute a function just before the startup screen. (90% of the code is already loaded) + * You can also specify a priority to change the execution order. + * In Open Ticket, this is used for the following processes: + * - Autoclose/delete + * - 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 { 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) diff --git a/src/core/api/modules/config.ts b/src/core/api/modules/config.ts index 8e635ed..796d1f6 100644 --- a/src/core/api/modules/config.ts +++ b/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 { constructor(debug:ODDebugger){ @@ -33,7 +33,7 @@ export class ODConfigManager extends ODManager { * 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. - * You will use this class to get & edit variables from the config files or to create your own config! + * This is an open ticket JSON 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") diff --git a/src/core/api/modules/console.ts b/src/core/api/modules/console.ts index b6e0943..d36ce20 100644 --- a/src/core/api/modules/console.ts +++ b/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 { diff --git a/src/core/api/modules/database.ts b/src/core/api/modules/database.ts index 24d4ab9..767f307 100644 --- a/src/core/api/modules/database.ts +++ b/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 { constructor(debug:ODDebugger){ @@ -35,7 +35,7 @@ export class ODDatabaseManager extends ODManager { * 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){ diff --git a/src/core/api/modules/event.ts b/src/core/api/modules/event.ts index 27633c1..9d52d8b 100644 --- a/src/core/api/modules/event.ts +++ b/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! - * Check out the `openticket.events` class! + * It's not recommended to create this class yourself. Plugin events should be registered in their `plugin.json` file instead. + * All events are available in the `openticket.events` global! */ export class ODEventManager extends ODManager { /**Reference to the Open Ticket debugger */ diff --git a/src/core/api/modules/language.ts b/src/core/api/modules/language.ts index 71a12c3..4cac88b 100644 --- a/src/core/api/modules/language.ts +++ b/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 { + /**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 { 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 ?? "" @@ -36,9 +56,11 @@ export class ODLanguageManager extends ODManager { {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 ?? "" @@ -48,16 +70,20 @@ export class ODLanguageManager extends ODManager { {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 { 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 { 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 diff --git a/src/core/api/modules/post.ts b/src/core/api/modules/post.ts index de5b5f6..b985b1c 100644 --- a/src/core/api/modules/post.ts +++ b/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> { /**A reference to the main server of the bot */ diff --git a/src/core/api/modules/worker.ts b/src/core/api/modules/worker.ts index 617beb1..7b9cf96 100644 --- a/src/core/api/modules/worker.ts +++ b/src/core/api/modules/worker.ts @@ -36,7 +36,7 @@ export class ODWorker 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 extends ODManager> { /**The order of execution for workers inside this manager. */