From 3ac10c6e2429e6e08f76fc9956b8ae4da185ae4f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Gro=C3=9F?= <git@minzkraut.com>
Date: Mon, 3 Apr 2023 15:23:14 +0200
Subject: [PATCH] Docs: Add docs for collection and view commands

---
 commands/collection.js | 23 +++++++++++++++++++++++
 commands/view.js       | 26 ++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/commands/collection.js b/commands/collection.js
index 1c2cb06..f9d698b 100644
--- a/commands/collection.js
+++ b/commands/collection.js
@@ -97,6 +97,15 @@ module.exports = {
 
     },
 
+    /**
+     * A function to generate pagination components with optional features.
+     *
+     * @param {string} uid - The unique (component)ID for the pagination.
+     * @param {boolean} [prev=true] - Whether the "Previous" button should be enabled or disabled. Defaults to true.
+     * @param {boolean} [next=true] - Whether the "Next" button should be enabled or disabled. Defaults to true.
+     * @param {boolean} [groupDupes=false] - Whether the "Group Dupes" button should be checked or unchecked. Defaults to false (unchecked).
+     * @returns {ActionRowBuilder} An ActionRowBuilder object containing three ButtonBuilder objects for "Previous", "Next", and "Group Dupes" buttons. .
+     */
     getPaginateComponents(uid, prev=true, next=true, groupDupes=false) {
         //add buttons for pagination
         let row = new ActionRowBuilder();
@@ -122,6 +131,19 @@ module.exports = {
         return row;
     },
 
+    /**
+     * Updates the page embed of a user's card collection with pagination and filtering.
+     * This method has the side-effect of actively updating the passed embed!
+     *
+     * @function updatePageEmbed
+     * @param {string} uid - The unique (component)ID of the embed components.
+     * @param {Object} i - The embed message object.
+     * @param {Object} user - The user object (discord snowflake).
+     * @param {number} offset - The offset to start pagination.
+     * @param {boolean} group - True if cards should be grouped by character, false otherwise.
+     * @param {Object} filterParam - An object containing filters (character, group, and quality) to apply.
+     * @returns {Promise<void>} A promise that resolves when the embed is updated.
+     */
     async updatePageEmbed(uid, i, user, offset, group, filterParam) {
         let cards;
         let filter = {
@@ -136,6 +158,7 @@ module.exports = {
             offset: offset
         }
         
+        //The parameter "group" refers to character grouping and is unrelated to the entity of type group!!
         if (group)  {
             filter["attributes"] = ["characterId", [Card.sequelize.fn("COUNT", "characterId"), "count"]];
             filter["order"] = [[Card.sequelize.literal("count"), "DESC"]];
diff --git a/commands/view.js b/commands/view.js
index 13cc973..7716580 100644
--- a/commands/view.js
+++ b/commands/view.js
@@ -50,6 +50,12 @@ module.exports = {
         }
     },
 
+    /**
+     * View a card by its identifier and create an embed for it
+     * @param {Interaction} interaction - The interaction object that triggered this function
+     * @param {string} cardIdentifier - The identifier of the card to view
+     * @returns {Promise<void>} - A promise that resolves once the card has been viewed and an embed has been created
+     */
     async viewCard(interaction, cardIdentifier) {
         let card = await Card.findOne({
             where: {
@@ -105,6 +111,15 @@ module.exports = {
         const message = await interaction.editReply({ embeds: [embed], files: [cardImage], fetchReply: true });
     },
 
+    /**
+     * View a character by its ID and create an embed for it.
+     * If the member who triggered the interaction is an admin, also include an "Edit" button.
+     * (Edits the passed interaction reply)
+     * 
+     * @param {Interaction} interaction - The interaction object that triggered this function.
+     * @param {number} characterId - The ID of the character to view.
+     * @returns {Promise<void>} - A promise that resolves once the character has been viewed and an embed has been created.
+     */
     async viewCharacter(interaction, characterId) {
         let isAdmin = await UserUtils.getPermissionLevel(interaction.member) == 2;
         let character = await Character.findOne({ 
@@ -161,6 +176,8 @@ module.exports = {
                 );
         }
         let replyPayload = { embeds: [embed], files: [imagePath], fetchReply: true }
+
+        //the experimental Edit button is added if view is invoked by an admin
         if  (isAdmin) { replyPayload.components = [row]; }
         const message = await interaction.editReply(replyPayload);
         const filter = (m) => m.member.user.id === interaction.member.user.id;
@@ -174,6 +191,15 @@ module.exports = {
         });
     },
 
+    /**
+     * View a badge by its ID and create an embed for it
+     * (Edits the passed interaction reply)
+     * 
+     * @async
+     * @param {Interaction} interaction - The interaction object that triggered this function
+     * @param {number} badgeId - The ID of the badge to view
+     * @returns {Promise<void>} - A promise that resolves once the badge has been viewed and an embed has been created
+     */
     async viewBadge(interaction, badgeId) {
         let badge = await Badge.findOne({ 
             where: { id: badgeId },