Skip to content

Commit

Permalink
docs: improve jsdocs (#461)
Browse files Browse the repository at this point in the history 
**Please describe the changes this PR makes and why it should be
merged:**
#412
Continue of #413

**Status and versioning classification:**
- This PR **only** includes non-code changes, like changes to
documentation, README, etc.

<!--
Please move lines that apply to you out of the comment:
- This PR changes the library's interface (methods or parameters added)
- This PR includes breaking changes (methods removed or renamed,
parameters moved or removed)
-->
  • Loading branch information
@xhyrom
xhyrom authored Apr 29, 2023
2 parents 2efa5dd + 45e3fa2 commit e0ec5bc
Show file tree
Hide file tree
Showing 6 changed files with 309 additions and 27 deletions.
6 changes: 6 additions & 0 deletions src/lib/GClient.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,21 @@ export type GClientMessagePrefix = string | string[] | null;
*/
export enum AutoDeferType {
/**
* Automatically deferReply interaction (+ ephemeral) if application doesn't respond in 3s
* @example interaction.deferReply({ ephemeral: true })
* @type {number}
*/
'EPHEMERAL' = 1,
/**
* Automatically deferReply interaction if application doesn't respond in 3s
* @example interaction.deferReply()
* @type {number}
*/
'NORMAL' = 2,
/**
* Automatically deferUpdate interaction if application doesn't respond in 3s
* @example interaction.deferUpdate()
* @type {number}
*/
'UPDATE' = 3,
}
Expand Down
198 changes: 179 additions & 19 deletions src/lib/util/logger/Logger.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,26 +27,107 @@ export enum Events {
'PLUGIN_REGISTERED' = 'pluginRegistered',
}

/* eslint-disable max-len */
export interface LoggerEvents {
/**
* Emitted when a handler is run.
* @event Logger#handlerRun
* @param {import('../../structures/contexts/AutocompleteContext')|import('../../structures/contexts/CommandContext')|import('../../structures/contexts/ComponentContext')} ctx The type of handler.
*/
handlerRun: [ctx: AutocompleteContext | CommandContext | ComponentContext];
/**
* Emitted when a handler errors.
* @event Logger#handlerError
* @param {import('../../structures/contexts/AutocompleteContext')|import('../../structures/contexts/CommandContext')|import('../../structures/contexts/ComponentContext')} ctx The type of handler.
* @param {any} error The error that occurred.
*/
handlerError: [
ctx: AutocompleteContext | CommandContext | ComponentContext,
error: any,
];
/**
* Emitted when a command handler is run.
* @event Logger#commandHandlerRun
* @param {import('../../structures/contexts/CommandContext')} ctx The command context.
*/
commandHandlerRun: [ctx: CommandContext];
/**
* Emitted when a command handler errors.
* @event Logger#commandHandlerError
* @param {import('../../structures/contexts/CommandContext')} ctx The command context.
* @param {any} error The error that occurred.
*/
commandHandlerError: [ctx: CommandContext, error: any];
/**
* Emitted when an auto complete handler is run.
* @event Logger#autoCompleteHandlerRun
* @param {import('../../structures/contexts/AutocompleteContext')} ctx The auto complete context.
*/
autoCompleteHandlerRun: [ctx: AutocompleteContext];
/**
* Emitted when an auto complete handler errors.
* @event Logger#autoCompleteHandlerError
* @param {import('../../structures/contexts/AutocompleteContext')} ctx The auto complete context.
* @param {any} error The error that occurred.
*/
autoCompleteHandlerError: [ctx: AutocompleteContext, error: any];
/**
* Emitted when a component handler is run.
* @event Logger#componentHandlerRun
* @param {import('../../structures/contexts/ComponentContext')} ctx The component context.
*/
componentHandlerRun: [ctx: ComponentContext];
/**
* Emitted when a component handler errors.
* @event Logger#componentHandlerError
* @param {import('../../structures/contexts/ComponentContext')} ctx The component context.
* @param {any} error The error that occurred.
*/
componentHandlerError: [ctx: ComponentContext, error: any];
/**
* Emitted when a command is registered.
* @event Logger#commandRegistered
* @param {import('../../structures/Command')} command The command that was registered.
*/
commandRegistered: [command: Command];
/**
* Emitted when a command is unregistered.
* @event Logger#commandUnregistered
* @param {import('../../structures/Command')} command The command that was unregistered.
*/
commandUnregistered: [command: Command];
/**
* Emitted when a component is registered.
* @event Logger#componentRegistered
* @param {import('../../structures/Component')} component The component that was registered.
*/
componentRegistered: [component: Component];
/**
* Emitted when a component is unregistered.
* @event Logger#componentUnregistered
* @param {import('../../structures/Component')} component The component that was unregistered.
*/
componentUnregistered: [component: Component];
/**
* Emitted when a listener is registered.
* @event Logger#listenerRegistered
* @param {import('../../structures/Listener')} listener The listener that was registered.
*/
listenerRegistered: [listener: Listener];
/**
* Emitted when a listener is unregistered.
* @event Logger#listenerUnregistered
* @param {import('../../structures/Listener')} listener The listener that was unregistered.
*/
listenerUnregistered: [listener: Listener];
/**
* Emitted when a plugin is registered.
* @event Logger#pluginRegistered
* @param {import('../../structures/Plugin')} plugin The plugin that was registered.
*/
pluginRegistered: [plugin: Plugin];
}
/* eslint-enable max-len */

export declare interface ILogger {
on<U extends keyof LoggerEvents>(event: U, listener: LoggerEvents[U]): this;
Expand Down Expand Up @@ -94,15 +175,42 @@ export declare interface ILogger {
}

export const enum LogLevel {
/**
* Logs everything.
* @type {number}
* @default
*/
TRACE = 1,
/**
* Logs everything except trace messages.
* @type {number}
*/
DEBUG = 2,
/**
* Logs everything except trace and debug messages.
* @type {number}
*/
INFO = 3,
/**
* Logs everything except trace, debug and info messages.
* @type {number}
* @deprecated
*/
TIME = 4,
/**
* Logs everything except trace, debug, info and time messages.
* @type {number}
*/
WARN = 5,
/**
* Logs everything except trace, debug, info, time and warn messages.
* @type {number}
*/
ERROR = 8,
/**
* Turn off all logging.
* @type {number}
*/
OFF = 99,
}

Expand All @@ -116,14 +224,14 @@ export type LogMethods =
| 'error';

export class ILogger extends EventEmitter {
TRACE: LogLevel.TRACE;
DEBUG: LogLevel.DEBUG;
INFO: LogLevel.INFO;
TIME: LogLevel.TIME;
WARN: LogLevel.WARN;
ERROR: LogLevel.ERROR;
OFF: LogLevel.OFF;
level: LogLevel = LogLevel.TRACE;
public TRACE: LogLevel.TRACE;
public DEBUG: LogLevel.DEBUG;
public INFO: LogLevel.INFO;
public TIME: LogLevel.TIME;
public WARN: LogLevel.WARN;
public ERROR: LogLevel.ERROR;
public OFF: LogLevel.OFF;
public level: LogLevel = LogLevel.TRACE;

constructor() {
super();
Expand All @@ -137,40 +245,70 @@ export class ILogger extends EventEmitter {
this.OFF = LogLevel.OFF;
}

/**
* Logs a message at the trace level.
* @param {unknown[]} values
*/
public trace(...values: readonly unknown[]): void {
this.invoke(LogLevel.TRACE, ...values);
}

/**
* Logs a message at the debug level.
* @param {unknown[]} values
*/
public debug(...values: readonly unknown[]): void {
this.invoke(LogLevel.DEBUG, ...values);
}

/**
* Logs a message at the info level.
* @param {unknown[]} values
*/
public info(...values: readonly unknown[]): void {
this.invoke(LogLevel.INFO, ...values);
}

/**
* Logs a message at the time level.
* @param {unknown[]} values
* @deprecated
*/
public time(val: string): void {
if (val.length > 0) this.invokeTime(LogLevel.TIME, val, 'start');
}

/**
* Logs a message at the time level.
* @param {unknown[]} values
* @deprecated
*/
public timeEnd(val: string): void {
if (val.length > 0) this.invokeTime(LogLevel.TIME, val, 'stop');
}

/**
* Logs a message at the warn level.
* @param {unknown[]} values
*/
public warn(...values: readonly unknown[]): void {
this.invoke(LogLevel.WARN, ...values);
}

/**
* Logs a message at the error level.
* @param {unknown[]} values
*/
public error(...values: readonly unknown[]): void {
this.invoke(LogLevel.ERROR, ...values);
}

/**
* Logs a message at the given level.
* @param {LogLevel} level
* @param {unknown[]} values
* @returns {void}
*/
public invoke(level: LogLevel, ...values: readonly unknown[]): void {
if (!this.enabledFor(level)) return;

Expand Down Expand Up @@ -200,32 +338,45 @@ export class ILogger extends EventEmitter {
}

/**
* @deprecated
* Logs a time message at the given level.
* @param {LogLevel} level
* @param {unknown[]} values
* @param {'start' | 'stop'} type
* @returns {void}
*/
public invokeTime(level: LogLevel, val: string, type: 'start' | 'stop') {
public invokeTime(
level: LogLevel,
val: string,
type: 'start' | 'stop',
): void {
if (!this.enabledFor(level)) return;

if (type == 'start') console.time(val);
else console.timeEnd(val);
}

protected readonly LevelMethods = new Map<LogLevel, LogMethods>([
[LogLevel.TRACE, 'trace'],
[LogLevel.DEBUG, 'debug'],
[LogLevel.INFO, 'info'],
[LogLevel.TIME, 'time'],
[LogLevel.WARN, 'warn'],
[LogLevel.ERROR, 'error'],
]);

/**
* Sets the log level.
* @param {LogLevel} level
* @returns {void}
*/
public setLevel(level: LogLevel): void {
this.level = level;
}

/**
* Gets the log level.
* @returns {LogLevel}
*/
public getLevel(): LogLevel {
return this.level;
}

/**
* Checks if the given level is enabled.
* @param {LogLevel} level
* @returns {boolean}
*/
public enabledFor(level: LogLevel): boolean {
return level >= this.level;
}
Expand Down Expand Up @@ -257,6 +408,15 @@ export class ILogger extends EventEmitter {
public createDefaultHandler(): void {
this.warn('This feature is not supported.');
}

protected readonly LevelMethods = new Map<LogLevel, LogMethods>([
[LogLevel.TRACE, 'trace'],
[LogLevel.DEBUG, 'debug'],
[LogLevel.INFO, 'info'],
[LogLevel.TIME, 'time'],
[LogLevel.WARN, 'warn'],
[LogLevel.ERROR, 'error'],
]);
}

export const Logger = new ILogger();
Loading

0 comments on commit e0ec5bc

Please sign in to comment.