Documentation complete

modules/core/commands/modules.ts

@@ -4,8 +4,6 @@
  * Replies module listing as well as description of each.
  *
  * Just for the information I guess...
- *
- * @packageDocumentation
  */
 
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";

modules/core/commands/ping.ts

@@ -4,8 +4,6 @@
  * Replies websocket ping (ping between bot and discord) and real ping (ping to fetch + process).
  *
  * @remarks Probably should double their value as two ways, but nvm.
- *
- * @packageDocumentation
  */
 
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";

modules/core/events/interaction-create.ts

@@ -4,9 +4,8 @@
  * Resolves creation of an interaction by users.
  *
  * @remark Only {@link ChatInputCommand} currently being resolved.
- *
- * @packageDocumentation
  */
+
 import { Events, Interaction } from "discord.js";
 
 import Client from "$lib/client.js";

modules/core/events/ready.ts

@@ -5,8 +5,6 @@
  *
  * @remarks Will push slash commands, set activity status,
  * and log bot's initials.
- *
- * @packageDocumentation
  */
 
 import { generateDependencyReport } from "@discordjs/voice";

modules/core/module.ts

@@ -11,7 +11,7 @@
  *
  *  There a lot of speaking because it's as important as $lib.
  *
- * @packageDocumentation
+ *  @packageDocumentation
  */
 
 const name = "core";

modules/music/commands/clear.ts

@@ -1,12 +1,25 @@
+/**
+ * /clear
+ *
+ * Clears Player queue entirely.
+ *
+ * Possible replies:
+ * - Success with amount of tracks deleted.
+ * - Player does not exists.
+ */
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction): Promise<void> {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/connect.ts

@@ -1,12 +1,29 @@
+/**
+ * /connect
+ *
+ * Connects bot to the voice channel.
+ *
+ * Just like play but without query.
+ *
+ * Possible replies:
+ * - Success with Voice Channel bot connected to.
+ * - Requester does not connected to the Voice Channel.
+ *
+ * @deprecated Does not make sense.
+ */
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction): Promise<void> {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/filter.ts

@@ -1,13 +1,30 @@
+/**
+ * /filter <filter id>
+ *
+ * Toggles filter that will be applied to the playback.
+ * Such as nightcore, etc.
+ *
+ * If no filter id was provided clears them all.
+ *
+ * Possible replies:
+ * - Success with chosen filter status or filters being cleared.
+ * - Player does not exists.
+ */
+
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import Filter from "../lib/filter.js";
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 
@@ -36,7 +53,7 @@ const data = new SlashCommandBuilder()
         option
             .setName("filter")
             .setDescription("Filter to apply.")
-            .setChoices(...Object.values(Filter.FILTERS))
+            .setChoices(...Filter.filterChoices())
     )
     .setDMPermission(false);
 

modules/music/commands/info.ts

@@ -1,12 +1,32 @@
+/**
+ * /info
+ *
+ * Replies with very stylish player info card.
+ *
+ * Playback status bar with title, thumbnail and duration.
+ * Queue length and duration.
+ * Applied filters.
+ * Current loop option.
+ * Player lifetime.
+ *
+ * Possible replies:
+ * - Success with info card.
+ * - Player does not exists.
+ */
+
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/insert.ts

@@ -1,12 +1,26 @@
+/**
+ * /insert (query) (position)
+ *
+ * Inserts specified track/album to the position specified.
+ *
+ * Possible replies:
+ * - Success with first added track info.
+ * - Player does not exists.
+ * - No track was added.
+ */
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/jump.ts

@@ -1,12 +1,29 @@
+/**
+ * /jump (query)
+ *
+ * Jumps to the specified Track from the queue.
+ * If number was provided - resolves as position at where queue position should be set.
+ * If string was provided - jumps to the most similar if terms of {@link ../lib/misc#LargestCommonSequence} Track title.
+ *
+ * Possible replies:
+ * - Success with selected track data.
+ * - Such track does not exists, though cannot be jumped to.
+ * - Player does not exists.
+ */
+
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/loop.ts

@@ -1,13 +1,29 @@
+/**
+ * /loop (option)
+ *
+ * Changes loop option.
+ *
+ * @remarks
+ * @see {@link ../lib/types} for LoopOption definition.
+ *
+ * Possible replies:
+ * - Success with new loop option.
+ * - Player does not exists.
+ */
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
 import { LoopOption } from "../lib/types.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/next.ts

@@ -1,12 +1,25 @@
+/**
+ * /next
+ *
+ * Skips current track.
+ *
+ * Possible replies:
+ * - Success with confirmation of skip. (even there is nothing to skip)
+ * - Player does not exists.
+ */
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/pause.ts

@@ -1,12 +1,25 @@
+/**
+ * /pause
+ *
+ * Toggles playback pause.
+ *
+ * Possible replies:
+ * - Success with setted state (paused, resumed).
+ * - Player does not exists.
+ */
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/play.ts

@@ -1,12 +1,27 @@
+/**
+ * /play <query>
+ *
+ * Starts up the Player.
+ * If query provided searches corresponding track/album and adds it to the queue end.
+ *
+ * Possible replies:
+ * - Success with first added track info.
+ * - Denies if requester is not connected to the Voice Channel.
+ * - No track was added, but player was set.
+ */
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/queue.ts

@@ -1,3 +1,20 @@
+/**
+ * /queue
+ *
+ * Replies interactive queue with current playing track at the top and 10 tracks from queue on each page.
+ * Interactiveness provided by buttons:
+ * - First page.
+ * - Previous page.
+ * - Next page.
+ * - Last page.
+ *
+ * Buttons live up to 30 seconds.
+ *
+ * Possible replies:
+ * - Success with interactive queue.
+ * - Player does not exists.
+ */
+
 import {
     ActionRowBuilder,
     ButtonBuilder,
@@ -10,11 +27,15 @@ import {
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/remove.ts

@@ -1,12 +1,28 @@
+/**
+ * /remove (query)
+ *
+ * Removes Track from the queue.
+ * If number was provided - resolves as position at where deletion should occurr.
+ * If string was provided - removes most similar if terms of {@link ../lib/misc#LargestCommonSequence} Track title.
+ *
+ * Possible replies:
+ * - Success with removed track data.
+ * - Such track does not exists, though cannot be removed.
+ * - Player does not exists.
+ */
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/reshuffle.ts

@@ -1,12 +1,26 @@
+/**
+ * /reshuffle
+ * Shuffles the queue, so real order is changed.
+ * DO NOT Confuse it with AUTO LoopOption.
+ *
+ * Possible replies:
+ * - Success with queue being reshuffled.
+ * - Player does not exists.
+ */
+
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/seek.ts

@@ -1,12 +1,31 @@
+/**
+ * /seek <hrs> <mins> <secs>
+ *
+ * Changes current Track playback duration to value given.
+ *
+ * @remarks
+ * If not stated - default value for all imputs is 0.
+ * Input resolution is defined by FFmpeg.
+ *
+ * Possible replies:
+ * - Success with previous and new playback duration.
+ * - Player does not exists.
+ * - No resource is currently playing.
+ */
+
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/stop.ts

@@ -1,12 +1,27 @@
+/**
+ * /stop
+ *
+ * Destroys player of the Guild where it was emitted.
+ * Also disconnects user from Voice Channel Quetza was in.
+ *
+ * Possible replies:
+ * - Success with player being destroyed.
+ * - Player does not exists.
+ */
+
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 

modules/music/commands/volume.ts

@@ -1,19 +1,34 @@
+/**
+ * /volume (amount)
+ *
+ * Sets volume of {@link ../lib/player#Player | Player} in percent scale,
+ * clamping it in range defined in Player.
+ *
+ * Possible replies:
+ * - Success with new volume value.
+ * - Player does not exists.
+ */
+
 import { ChatInputCommandInteraction, SlashCommandBuilder } from "discord.js";
 
 import Client from "$lib/client.js";
 import logger from "$lib/logger.js";
+import Music from "$mlib/music.js";
 
 import replies from "../lib/replies.js";
-import { controller } from "../module.js";
 
-async function execute(client: Client, interaction: ChatInputCommandInteraction) {
+async function execute(
+    _: Client,
+    interaction: ChatInputCommandInteraction,
+    controller: Music
+): Promise<void> {
     if (!interaction.isChatInputCommand() || !interaction.inCachedGuild() || !interaction.channel) {
         logger.warn("Interaction rejected.", { interaction });
 
         return;
     }
 
-    const volume = interaction.options.getInteger("volume") ?? 100;
+    const volume = interaction.options.getInteger("volume", true);
 
     const player = controller.get(interaction.guild, interaction.channel);
 

modules/music/events/voice-state-update.ts

@@ -3,8 +3,6 @@
  *
  * Monitors voice states of attended guilds.
  * If Quetza happens to be alone in the Voice Channel - destroys guilds player and disconnects.
- *
- * @packageDocumentation
  */
 
 import { BaseGuildVoiceChannel, User, VoiceState } from "discord.js";

modules/music/lib/MusicError.ts

@@ -1,7 +1,5 @@
 /**
  * @see ../../../src/lib/error.ts
- *
- * @packageDocumentation
  */
 
 import QuetzaError from "$lib/error.js";

modules/music/lib/filter.ts

@@ -52,6 +52,18 @@ export default class Filter {
      */
     private switches_ = new Map<filterPreset, filterValue>();
 
+    /**
+     * Returns filters as Discord API Choices compatible array.
+     *
+     * @returns {@link Filter#FILTERS} as { name: FILTERS[key].name, value: key }.
+     */
+    public static filterChoices(): { name: string; value: string }[] {
+        return Object.entries(Filter.FILTERS).map(([key, value]) => ({
+            name: value.name,
+            value: key
+        }));
+    }
+
     /**
      * Converts active {@link filterValue | filterValues} to array.
      *
@@ -101,9 +113,9 @@ export default class Filter {
     }
 
     /**
-     * Converts active filters to FFmpeg compatable argument.
+     * Converts active filters to FFmpeg compatible argument.
      *
-     * @returns FFmpeg compatable argument representing active filters.
+     * @returns FFmpeg compatible argument representing active filters.
      */
     public toString(): string {
         return this.toggled()