document code with jsdoc comments

.eslintignore

@@ -4,6 +4,7 @@ node_modules
 .env
 .env.*
 !.env.example
+docs
 
 # Ignore files for PNPM, NPM and YARN
 pnpm-lock.yaml

.eslintrc.json

@@ -8,5 +8,8 @@
 		"ecmaVersion": "latest",
 		"sourceType": "module"
 	},
-	"rules": {}
+	"plugins": ["jsdoc"],
+	"rules": {
+		"jsdoc/no-undefined-types": 1
+	}
 }

.jsdoc.conf.json

@@ -1,7 +1,7 @@
 {
 	"source": {
 		"include": ["."],
-    "includePattern": ".+\\.js(doc|x)?$",
-    "excludePattern": "node_modules"
+		"exclude": ["node_modules", "commands/examples"],
+		"includePattern": ".+\\.js(doc|x)?$"
 	}
 }

.prettierignore

@@ -4,6 +4,7 @@ node_modules
 .env
 .env.*
 !.env.example
+docs
 
 # Ignore files for PNPM, NPM and YARN
 pnpm-lock.yaml

README.md

@@ -159,7 +159,6 @@ Registered Voice Channels will automatically:
 
 # TO-DO List:
 
-
 > **NOTE**
 > These lists can and will easily be appended to in the future. Any and all feedback is greatly appreciated!
 

commands/admin/custom_vc/slash.js

@@ -1,4 +1,9 @@
-import { ChannelType, PermissionFlagsBits, SlashCommandBuilder } from 'discord.js';
+import {
+	ChannelType,
+	PermissionFlagsBits,
+	SlashCommandBuilder,
+	ChatInputCommandInteraction
+} from 'discord.js';
 import { VoiceChannel } from '../../../database.js';
 
 export const data = new SlashCommandBuilder()
@@ -41,9 +46,11 @@ export const data = new SlashCommandBuilder()
 					.setDescription('The voice channel to be unregistered.')
 			)
 	);
+/** @param {ChatInputCommandInteraction} interaction */
 export async function execute(interaction) {
 	const { guild, options } = interaction;
 
+	/** @type {string} */
 	let step;
 	try {
 		switch (options.getSubcommand()) {

commands/admin/self_roles/context/add.js

@@ -1,9 +1,13 @@
-import { PermissionFlagsBits, TextInputBuilder, TextInputStyle } from 'discord.js';
 import {
 	ModalBuilder,
+	TextInputStyle,
 	ActionRowBuilder,
+	TextInputBuilder,
+	PermissionFlagsBits,
+	ModalSubmitInteraction,
 	ApplicationCommandType,
-	ContextMenuCommandBuilder
+	ContextMenuCommandBuilder,
+	ContextMenuCommandInteraction
 } from 'discord.js';
 import { addSelfRoles } from '../../../../shared.js';
 
@@ -12,6 +16,7 @@ export const data = new ContextMenuCommandBuilder()
 	.setName('Add role emoji pair')
 	.setType(ApplicationCommandType.Message)
 	.setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles);
+/** @param {ModalSubmitInteraction} interaction */
 export async function modalSubmit(interaction) {
 	const { fields, guild } = interaction;
 	// Get text inputs from modal
@@ -32,6 +37,7 @@ export async function modalSubmit(interaction) {
 
 	await addSelfRoles(interaction, message, role, emoji);
 }
+/** @param {ContextMenuCommandInteraction} interaction */
 export async function execute(interaction) {
 	const modal = new ModalBuilder()
 		.setCustomId('Add role emoji pair-pair')

commands/admin/self_roles/context/register.js

@@ -1,11 +1,17 @@
+import {
+	ApplicationCommandType,
+	ContextMenuCommandBuilder,
+	PermissionFlagsBits,
+	ContextMenuCommandInteraction
+} from 'discord.js';
 import { Message } from '../../../../database.js';
-import { ApplicationCommandType, ContextMenuCommandBuilder, PermissionFlagsBits } from 'discord.js';
 
 export const data = new ContextMenuCommandBuilder()
 	.setDMPermission(false)
 	.setName('Register self roles')
 	.setType(ApplicationCommandType.Message)
 	.setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles);
+/** @param {ContextMenuCommandInteraction} interaction */
 export async function execute(interaction) {
 	const id = interaction.targetMessage.id;
 

commands/admin/self_roles/context/remove.js

@@ -1,11 +1,17 @@
+import {
+	ApplicationCommandType,
+	ContextMenuCommandBuilder,
+	PermissionFlagsBits,
+	ContextMenuCommandInteraction
+} from 'discord.js';
 import { removeSelfRoles } from '../../../../shared.js';
-import { ApplicationCommandType, ContextMenuCommandBuilder, PermissionFlagsBits } from 'discord.js';
 
 export const data = new ContextMenuCommandBuilder()
 	.setDMPermission(false)
 	.setName('Remove self roles')
 	.setType(ApplicationCommandType.Message)
 	.setDefaultMemberPermissions(PermissionFlagsBits.ManageRoles);
+/** @param {ContextMenuCommandInteraction} interaction */
 export async function execute(interaction) {
 	const id = interaction.targetMessage.id;
 	await removeSelfRoles(interaction, id);

commands/admin/self_roles/slash.js

@@ -1,7 +1,12 @@
-import { addSelfRoles } from '../../../shared.js';
-import { PermissionFlagsBits, SlashCommandBuilder } from 'discord.js';
+import { PermissionFlagsBits, SlashCommandBuilder, ChatInputCommandInteraction } from 'discord.js';
+import { addSelfRoles, removeSelfRoles } from '../../../shared.js';
 import { Message } from '../../../database.js';
 
+/**
+ * Sends a `Message` in the current channel and registers for self roles.
+ * @param {ChatInputCommandInteraction} interaction
+ * @returns {string}
+ */
 const createSelfRoles = async (interaction) => {
 	const { options, channel } = interaction;
 
@@ -16,6 +21,17 @@ const createSelfRoles = async (interaction) => {
 	return id;
 };
 
+/**
+ * @typedef {Object} SelfRoleResponse
+ * @property {boolean} success Whether or not the operation was successful.
+ * @property {string|null} msgID A Discord message ID, if successful.
+ */
+
+/**
+ * Registers a `Message` for self roles.
+ * @param {ChatInputCommandInteraction} interaction
+ * @returns {Promise<SelfRoleResponse>}
+ */
 const registerSelfRoles = async (interaction) => {
 	const { options, channel } = interaction;
 	const id = options.getString('id');
@@ -50,7 +66,12 @@ const registerSelfRoles = async (interaction) => {
 	return response;
 };
 
-const removeSelfRoles = async (interaction, msgID) => {
+/**
+ * Main logic of the 'Self Roles remove' slash command to remove the functionality from a `Message`.
+ * @param {ChatInputCommandInteraction} interaction
+ * @param {string} msgID A Discord message ID.
+ */
+const removeReactionRoles = async (interaction, msgID) => {
 	const { channel } = interaction;
 
 	try {
@@ -66,6 +87,7 @@ const removeSelfRoles = async (interaction, msgID) => {
 		return;
 	}
 
+	// Call shared method for further logic
 	await removeSelfRoles(interaction, msgID);
 };
 
@@ -124,11 +146,13 @@ export const data = new SlashCommandBuilder()
 					.setDescription('The ID to reference the message to be removed.')
 			)
 	);
+/** @param {ChatInputCommandInteraction} interaction */
 export async function execute(interaction) {
 	const { options } = interaction;
 
-	let createNew = false,
-		id;
+	/** @type {string=} */
+	let id;
+	let createNew = false;
 	switch (options.getSubcommand()) {
 		case 'create':
 			id = await createSelfRoles(interaction);
@@ -153,7 +177,7 @@ export async function execute(interaction) {
 		}
 		case 'remove': {
 			const msgID = options.getString('id');
-			await removeSelfRoles(interaction, msgID);
+			await removeReactionRoles(interaction, msgID);
 			break;
 		}
 	}

database.js

@@ -6,6 +6,7 @@ import { config } from 'dotenv';
 config();
 
 const { DB_NAME } = process.env;
+/** The database instance used as an ORM in this project. */
 const sequelize = new Sequelize({
 	storage: `${DB_NAME}.sqlite`,
 	dialect: 'sqlite',

deploy.js

@@ -3,13 +3,17 @@ import { REST, Routes } from 'discord.js';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { config } from 'dotenv';
+import Module from 'module';
 
 config();
 
 // Construct and prepare an instance of the REST module
 const rest = new REST().setToken(process.env.TOKEN);
 
-// and deploy your commands!
+/**
+ * Calls HTTP PUT to register commands in discord.
+ * @param {Array<Object>} commands
+ */
 const putCommands = async (commands) => {
 	try {
 		console.info(`[INFO] Started refreshing ${commands.length} application (/) commands.`);
@@ -32,7 +36,7 @@ getFiles(cmdPath)
 	// For each command file
 	.then(async (files) =>
 		(await Promise.all(files.map(importAndCheck)))
-			.filter((module) => module !== 0)
-			.map((module) => module.data.toJSON())
+			.filter(/** @param {(Module|0)} module */ (module) => module !== 0)
+			.map(/** @param {Module} module */ (module) => module.data.toJSON())
 	)
 	.then(putCommands);

events/channels/channelDelete.js

@@ -1,7 +1,8 @@
-import { ChannelType, Events } from 'discord.js';
+import { ChannelType, Events, GuildChannel } from 'discord.js';
 import { VoiceChannel } from '../../database.js';
 
 export const name = Events.ChannelDelete;
+/** @param {GuildChannel} channel */
 export async function execute(channel) {
 	if (channel.type !== ChannelType.GuildVoice) return;
 

events/channels/voiceStateUpdate.js

@@ -1,4 +1,12 @@
-import { ChannelType, Events, PermissionFlagsBits } from 'discord.js';
+import {
+	ChannelType,
+	Events,
+	PermissionFlagsBits,
+	GuildMember,
+	GuildChannelManager,
+	GuildChannel,
+	VoiceState
+} from 'discord.js';
 import { VoiceChannel } from '../../database.js';
 
 const vcPermissionOverwrites = [
@@ -17,6 +25,13 @@ const vcPermissionOverwrites = [
 	PermissionFlagsBits.Speak
 ];
 
+/**
+ * Function that either creates a new custom channel or gets an existing one registered in the database.
+ * @param {GuildMember} member The member that caused this event.
+ * @param {GuildChannelManager} guildChs All channels in this guild.
+ * @param {GuildChannel} channel The channel the member joined for this event to trigger.
+ * @returns {Promise<GuildChannel>} The channel, whether it's newly created or not.
+ */
 const getChannel = async (member, guildChs, channel) => {
 	// Check database for existing channel
 	const ownCh = await VoiceChannel.findOne({
@@ -52,6 +67,10 @@ const getChannel = async (member, guildChs, channel) => {
 	return privCh;
 };
 
+/**
+ * Function to delete the voice channel, if and only if the user is currently leaving and it was a custom channel.
+ * @param {VoiceState} state The previous voice state the user was in.
+ */
 const leftVoiceChat = async (state) => {
 	const { channel } = state;
 
@@ -77,8 +96,12 @@ const leftVoiceChat = async (state) => {
 };
 
 export const name = Events.VoiceStateUpdate;
+/**
+ * @param {VoiceState} oldState
+ * @param {VoiceState} newState
+ */
 export async function execute(oldState, newState) {
-	const { channel } = newState
+	const { channel } = newState;
 	await leftVoiceChat(oldState);
 	if (!channel) return;
 

events/interactionCreate.js

@@ -1,5 +1,11 @@
 import { Events } from 'discord.js';
+import Module from 'module';
 
+/**
+ * A more precise execution function specifically to call the main property of a module.
+ * @param {import('discord.js').Interaction} interaction
+ * @param {Module} command
+ */
 const executeCommand = async (interaction, command) => {
 	// Try executing command
 	try {
@@ -21,6 +27,14 @@ const executeCommand = async (interaction, command) => {
 	}
 };
 
+/**
+ * A generic execution function to call command methods.
+ * @param {import('discord.js').Interaction} interaction
+ * @param {Module} command
+ * @param {string} name
+ * @param {string=} description
+ * @param {string=} cmdName
+ */
 const genericExecute = async (interaction, command, name, description, cmdName) => {
 	try {
 		console.info(
@@ -35,7 +49,9 @@ const genericExecute = async (interaction, command, name, description, cmdName)
 };
 
 export const name = Events.InteractionCreate;
+/** @param {import('discord.js').Interaction} interaction */
 export async function execute(interaction) {
+	/** @type {Module} */
 	let command = interaction.client.commands.get(interaction.commandName);
 
 	// Execute slash- and context-menu-commands

events/messages/messageDelete.js

@@ -1,7 +1,8 @@
-import { Events } from 'discord.js';
 import { Message } from '../../database.js';
+import { Events } from 'discord.js';
 
 export const name = Events.MessageDelete;
+/** @param {import('discord.js').Message} message */
 export async function execute(message) {
 	// Delete message entry once message is deleted itself
 	const count = await Message.destroy({

events/messages/reactionAdd.js

@@ -1,10 +1,14 @@
-import { config } from 'dotenv';
-import { Events } from 'discord.js';
+import { Events, MessageReaction, User } from 'discord.js';
 import { Message, RoleEmojiPair } from '../../database.js';
+import { config } from 'dotenv';
 
 config();
 
 export const name = Events.MessageReactionAdd;
+/**
+ * @param {MessageReaction} reaction
+ * @param {User} user
+ */
 export async function execute(reaction, user) {
 	if (user.id === process.env.CLIENT) return;
 

events/messages/reactionRemove.js

@@ -1,10 +1,14 @@
-import { config } from 'dotenv';
-import { Events } from 'discord.js';
+import { Events, MessageReaction, User } from 'discord.js';
 import { Message, RoleEmojiPair } from '../../database.js';
+import { config } from 'dotenv';
 
 config();
 
 export const name = Events.MessageReactionRemove;
+/**
+ * @param {MessageReaction} reaction
+ * @param {User} user
+ */
 export async function execute(reaction, user) {
 	if (user.id === process.env.CLIENT) return;
 

events/ready.js

@@ -1,7 +1,8 @@
-import { Events } from 'discord.js';
+import { Events, Client } from 'discord.js';
 
 export const name = Events.ClientReady;
 export const once = true;
+/** @param {Client} client */
 export function execute(client) {
 	console.info(`[INFO] Ready! Logged in as ${client.user.tag}`);
 }

index.js

@@ -1,12 +1,17 @@
-import { Client, Collection, GatewayIntentBits } from 'discord.js';
+import { Client, Collection, GatewayIntentBits, Partials } from 'discord.js';
 import { getFiles, importAndCheck } from './shared.js';
-import { Partials } from 'discord.js';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { config } from 'dotenv';
+import Module from 'module';
 
 config();
 
+/**
+ * Main entry point, the bot logs on to discord.
+ * @param {Array<Module>} commands
+ * @param {Array<Module>} events
+ */
 const runClient = (commands, events) => {
 	// Create a new client instance
 	const client = new Client({
@@ -18,8 +23,15 @@ const runClient = (commands, events) => {
 		],
 		partials: [Partials.Message, Partials.Reaction]
 	});
+
+	/**
+	 * The commands registered for this client.
+	 * @type {Collection}
+	 */
 	client.commands = new Collection();
 	commands.forEach((c) => client.commands.set(c.data.name, c));
+
+	// Register client events
 	events.forEach((e) =>
 		e.once
 			? client.once(e.name, (...args) => e.execute(...args))

models/messages.js

@@ -1,5 +1,17 @@
-import { DataTypes } from 'sequelize';
+import { DataTypes, Sequelize } from 'sequelize';
 
+/**
+ * @typedef {Object} Message
+ * @property {string} id A Discord message ID.
+ * @method hasMany Defines an One-To-Many relationship.
+ * @param {Object}
+ */
+
+/**
+ * The definition of the `Message` table in the database.
+ * @param {Sequelize} sequelize
+ * @returns {Message}
+ */
 export default function (sequelize) {
 	return sequelize.define('Messages', {
 		id: {

models/roleEmojiPairs.js

@@ -1,5 +1,18 @@
-import { DataTypes, Deferrable } from 'sequelize';
+import { DataTypes, Deferrable, Sequelize } from 'sequelize';
 
+/**
+ * @typedef {Object} RoleEmojiPair
+ * @property {string} id A universally unique id, generated by sequelize.
+ * @property {string} message A Discord message ID as a foreign key reference.
+ * @property {string} role A Discord role ID.
+ * @property {string} emoji Either a unicode emoji or a string representation in Discord custom emoji format.
+ */
+
+/**
+ * The definition of the `RoleEmojiPair` table in the database.
+ * @param {Sequelize} sequelize
+ * @returns {RoleEmojiPair}
+ */
 export default function (sequelize) {
 	return sequelize.define('RoleEmojiPairs', {
 		id: {

models/voiceChannels.js

@@ -1,5 +1,17 @@
-import { DataTypes } from 'sequelize';
+import { DataTypes, Sequelize } from 'sequelize';
 
+/**
+ * @typedef {Object} VoiceChannel
+ * @property {string} id A Discord channel ID.
+ * @property {boolean} create Whether or not this channel is registered to create customs when joined.
+ * @property {(string|null)} owner The owner of this channel, if not registered for customs.
+ */
+
+/**
+ * The definition of the `VoiceChannel` table in the database.
+ * @param {Sequelize} sequelize
+ * @returns {VoiceChannel}
+ */
 export default function (sequelize) {
 	return sequelize.define('VoiceChannel', {
 		id: {

package-lock.json

@@ -17,6 +17,7 @@
 			"devDependencies": {
 				"eslint": "^8.56.0",
 				"eslint-config-prettier": "^9.1.0",
+				"eslint-plugin-jsdoc": "^48.0.6",
 				"prettier": "^3.1.1"
 			}
 		},
@@ -127,6 +128,20 @@
 				"node": ">=18"
 			}
 		},
+		"node_modules/@es-joy/jsdoccomment": {
+			"version": "0.42.0",
+			"resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.42.0.tgz",
+			"integrity": "sha512-R1w57YlVA6+YE01wch3GPYn6bCsrOV3YW/5oGGE2tmX6JcL9Nr+b5IikrjMPF+v9CV3ay+obImEdsDhovhJrzw==",
+			"dev": true,
+			"dependencies": {
+				"comment-parser": "1.4.1",
+				"esquery": "^1.5.0",
+				"jsdoc-type-pratt-parser": "~4.0.0"
+			},
+			"engines": {
+				"node": ">=16"
+			}
+		},
 		"node_modules/@eslint-community/eslint-utils": {
 			"version": "4.4.0",
 			"resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz",
@@ -476,6 +491,15 @@
 			"integrity": "sha512-lYe4Gx7QT+MKGbDsA+Z+he/Wtef0BiwDOlK/XkBrdfsh9J/jPPXbX0tE9x9cl27Tmu5gg3QUbUrQYa/y+KOHPQ==",
 			"optional": true
 		},
+		"node_modules/are-docs-informative": {
+			"version": "0.0.2",
+			"resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz",
+			"integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==",
+			"dev": true,
+			"engines": {
+				"node": ">=14"
+			}
+		},
 		"node_modules/are-we-there-yet": {
 			"version": "3.0.1",
 			"resolved": "https://registry.npmjs.org/are-we-there-yet/-/are-we-there-yet-3.0.1.tgz",
@@ -571,6 +595,18 @@
 				"ieee754": "^1.1.13"
 			}
 		},
+		"node_modules/builtin-modules": {
+			"version": "3.3.0",
+			"resolved": "https://registry.npmjs.org/builtin-modules/-/builtin-modules-3.3.0.tgz",
+			"integrity": "sha512-zhaCDicdLuWN5UbN5IMnFqNMhNfo919sH85y2/ea+5Yg9TsTkeZxpL+JLbp6cgYFS4sRLp3YV4S6yDuqVWHYOw==",
+			"dev": true,
+			"engines": {
+				"node": ">=6"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/cacache": {
 			"version": "15.3.0",
 			"resolved": "https://registry.npmjs.org/cacache/-/cacache-15.3.0.tgz",
@@ -681,6 +717,15 @@
 				"color-support": "bin.js"
 			}
 		},
+		"node_modules/comment-parser": {
+			"version": "1.4.1",
+			"resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.4.1.tgz",
+			"integrity": "sha512-buhp5kePrmda3vhc5B9t7pUQXAb2Tnd0qgpkIhPhkHXxJpiPJ11H0ZEU0oBpJ2QztSbzG/ZxMj/CHsYJqRHmyg==",
+			"dev": true,
+			"engines": {
+				"node": ">= 12.0.0"
+			}
+		},
 		"node_modules/concat-map": {
 			"version": "0.0.1",
 			"resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
@@ -939,6 +984,29 @@
 				"eslint": ">=7.0.0"
 			}
 		},
+		"node_modules/eslint-plugin-jsdoc": {
+			"version": "48.0.6",
+			"resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-48.0.6.tgz",
+			"integrity": "sha512-LgwXOX6TWxxFYcbdVe+BJ94Kl/pgjSPYHLzqEdAMXTA1BH9WDx7iJ+9/iDajPF64LtzWX8C1mCfpbMZjJGhAOw==",
+			"dev": true,
+			"dependencies": {
+				"@es-joy/jsdoccomment": "~0.42.0",
+				"are-docs-informative": "^0.0.2",
+				"comment-parser": "1.4.1",
+				"debug": "^4.3.4",
+				"escape-string-regexp": "^4.0.0",
+				"esquery": "^1.5.0",
+				"is-builtin-module": "^3.2.1",
+				"semver": "^7.6.0",
+				"spdx-expression-parse": "^4.0.0"
+			},
+			"engines": {
+				"node": ">=18"
+			},
+			"peerDependencies": {
+				"eslint": "^7.0.0 || ^8.0.0 || ^9.0.0"
+			}
+		},
 		"node_modules/eslint-scope": {
 			"version": "7.2.2",
 			"resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.2.2.tgz",
@@ -1356,6 +1424,21 @@
 			"resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
 			"integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew=="
 		},
+		"node_modules/is-builtin-module": {
+			"version": "3.2.1",
+			"resolved": "https://registry.npmjs.org/is-builtin-module/-/is-builtin-module-3.2.1.tgz",
+			"integrity": "sha512-BSLE3HnV2syZ0FK0iMA/yUGplUeMmNz4AW5fnTunbCIqZi4vG3WjJT9FHMy5D69xmAYBHXQhJdALdpwVxV501A==",
+			"dev": true,
+			"dependencies": {
+				"builtin-modules": "^3.3.0"
+			},
+			"engines": {
+				"node": ">=6"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/is-extglob": {
 			"version": "2.1.1",
 			"resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
@@ -1419,6 +1502,15 @@
 				"js-yaml": "bin/js-yaml.js"
 			}
 		},
+		"node_modules/jsdoc-type-pratt-parser": {
+			"version": "4.0.0",
+			"resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz",
+			"integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==",
+			"dev": true,
+			"engines": {
+				"node": ">=12.0.0"
+			}
+		},
 		"node_modules/json-buffer": {
 			"version": "3.0.1",
 			"resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
@@ -2191,9 +2283,9 @@
 			"optional": true
 		},
 		"node_modules/semver": {
-			"version": "7.5.4",
-			"resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz",
-			"integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==",
+			"version": "7.6.0",
+			"resolved": "https://registry.npmjs.org/semver/-/semver-7.6.0.tgz",
+			"integrity": "sha512-EnwXhrlwXMk9gKu5/flx5sv/an57AkRplG3hTK68W7FRDN+k+OWBj65M7719OkA82XLBxrcX0KSHj+X5COhOVg==",
 			"dependencies": {
 				"lru-cache": "^6.0.0"
 			},
@@ -2390,6 +2482,28 @@
 			"integrity": "sha512-WKa+XuLG1A1R0UWhl2+1XQSi+fZWMsYKffMZTTYsiZaUD8k2yDAj5atimTUD2TZkyCkNEeYE5NhFZmupOGtjYQ==",
 			"optional": true
 		},
+		"node_modules/spdx-exceptions": {
+			"version": "2.4.0",
+			"resolved": "https://registry.npmjs.org/spdx-exceptions/-/spdx-exceptions-2.4.0.tgz",
+			"integrity": "sha512-hcjppoJ68fhxA/cjbN4T8N6uCUejN8yFw69ttpqtBeCbF3u13n7mb31NB9jKwGTTWWnt9IbRA/mf1FprYS8wfw==",
+			"dev": true
+		},
+		"node_modules/spdx-expression-parse": {
+			"version": "4.0.0",
+			"resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-4.0.0.tgz",
+			"integrity": "sha512-Clya5JIij/7C6bRR22+tnGXbc4VKlibKSVj2iHvVeX5iMW7s1SIQlqu699JkODJJIhh/pUu8L0/VLh8xflD+LQ==",
+			"dev": true,
+			"dependencies": {
+				"spdx-exceptions": "^2.1.0",
+				"spdx-license-ids": "^3.0.0"
+			}
+		},
+		"node_modules/spdx-license-ids": {
+			"version": "3.0.17",
+			"resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.17.tgz",
+			"integrity": "sha512-sh8PWc/ftMqAAdFiBu6Fy6JUOYjqDJBJvIhpfDMyHrr0Rbp5liZqd4TjtQ/RgfLjKFZb+LMx5hpml5qOWy0qvg==",
+			"dev": true
+		},
 		"node_modules/sqlite3": {
 			"version": "5.1.7",
 			"resolved": "https://registry.npmjs.org/sqlite3/-/sqlite3-5.1.7.tgz",

package.json

@@ -22,6 +22,7 @@
 	"devDependencies": {
 		"eslint": "^8.56.0",
 		"eslint-config-prettier": "^9.1.0",
+		"eslint-plugin-jsdoc": "^48.0.6",
 		"prettier": "^3.1.1"
 	},
 	"type": "module"

shared.js

@@ -1,11 +1,18 @@
-import { join } from 'path';
-import { Op } from 'sequelize';
-import { config } from 'dotenv';
-import { readdir } from 'fs/promises';
+import { ChatInputCommandInteraction, ContextMenuCommandInteraction, Role } from 'discord.js';
 import { Message, RoleEmojiPair } from './database.js';
+import { readdir } from 'fs/promises';
+import { config } from 'dotenv';
+import { Op } from 'sequelize';
+import { join } from 'path';
+import Module from 'module';
 
 config();
 
+/**
+ * Main logic of the different 'Self Roles remove' commands to remove the functionality from a `Message`.
+ * @param {(ChatInputCommandInteraction|ContextMenuCommandInteraction)} interaction The interaction related to this command.
+ * @param {string} id A Discord message ID.
+ */
 export const removeSelfRoles = async (interaction, id) => {
 	// Try deleting message from database
 	const count = await Message.destroy({
@@ -27,6 +34,12 @@ export const removeSelfRoles = async (interaction, id) => {
 	console.info(`[INFO] Removed self roles from message with ID '${id}'.`);
 };
 
+/**
+ * Function to handle saving all the corresponding data for `Message` and `RoleEmojiPair` tables.
+ * @param {string} id A Discord message ID.
+ * @param {Role} role
+ * @param {string} emoji Either a unicode emoji or a string representation in Discord custom emoji format.
+ */
 const saveMessageData = async (id, role, emoji) => {
 	// Try finding message
 	const msg = await Message.findOne({ where: { id } });
@@ -56,6 +69,12 @@ const saveMessageData = async (id, role, emoji) => {
 	await RoleEmojiPair.create({ message: id, role: role.id, emoji });
 };
 
+/**
+ * Function to handle editing messages in case the message that's getting a new `RoleEmojiPair`, is owned by the bot.
+ * @param {import('discord.js').Message} message
+ * @param {Role} role
+ * @param {string} emoji Either a unicode emoji or a string representation in Discord custom emoji format.
+ */
 const editMessage = async (message, role, emoji) => {
 	if (message.author.id !== process.env.CLIENT) return;
 
@@ -72,6 +91,13 @@ const editMessage = async (message, role, emoji) => {
 	await message.edit(next);
 };
 
+/**
+ * Main logic of the different 'Self Roles add' commands to add a `RoleEmojiPair` to the database and the `Message`.
+ * @param {(ChatInputCommandInteraction|ContextMenuCommandInteraction)} interaction The interaction related to this command.
+ * @param {string} msgID A Discord message ID.
+ * @param {Role} role
+ * @param {string} emoji Either a unicode emoji or a string representation in Discord custom emoji format.
+ */
 export const addSelfRoles = async (interaction, msgID, role, emoji) => {
 	const { channel } = interaction;
 
@@ -109,9 +135,15 @@ export const addSelfRoles = async (interaction, msgID, role, emoji) => {
 	}
 };
 
+// Lists of required and optional attributes of command modules
 const required = ['data', 'execute'];
 const optional = ['autocomplete', 'modalSubmit'];
 
+/**
+ * Recursively scans a directory for all files in it.
+ * @param {string} dir
+ * @returns {Array<string>} Array of paths to the files within.
+ */
 export const getFiles = async (dir) => {
 	const dirents = await readdir(dir, { withFileTypes: true });
 	const files = await Promise.all(
@@ -123,6 +155,11 @@ export const getFiles = async (dir) => {
 	return Array.prototype.concat(...files);
 };
 
+/**
+ * Imports and checks a command from a path as a module.
+ * @param {string} filePath
+ * @returns {Promise<Module|0>}
+ */
 export const importAndCheck = async (filePath) => {
 	if (!filePath.endsWith('.js') || filePath.endsWith('.example.js')) {
 		// Skip this file