From b530ad027949ec5b94f5e7a5960e893985738e8f Mon Sep 17 00:00:00 2001 From: TetieWasTaken Date: Sun, 19 Mar 2023 19:16:57 +0100 Subject: [PATCH 1/7] docs: add more examples --- packages/discord.js/src/structures/Guild.js | 8 +++++++- packages/discord.js/src/structures/GuildMember.js | 15 +++++++++++++++ packages/discord.js/src/structures/Message.js | 5 +++++ packages/discord.js/src/structures/Role.js | 4 ++++ .../structures/interfaces/InteractionResponses.js | 1 + 5 files changed, 32 insertions(+), 1 deletion(-) diff --git a/packages/discord.js/src/structures/Guild.js b/packages/discord.js/src/structures/Guild.js index 4799d5db3ae3..87eddcd9ecda 100644 --- a/packages/discord.js/src/structures/Guild.js +++ b/packages/discord.js/src/structures/Guild.js @@ -1157,9 +1157,15 @@ class Guild extends AnonymousGuild { /** * Sets the guild's MFA level + * An elevated MFA level requires guild moderators to have 2FA enabled * @param {GuildMFALevel} level The MFA level * @param {string} [reason] Reason for changing the guild's MFA level * @returns {Promise} + * @example + * // Set the MFA level of the guild to Elevated + * guild.setMFALevel(GuildMFALevel.Elevated) + * .then(guild => console.log("Set guild's MFA level to Elevated")) + * .catch(console.error); */ async setMFALevel(level, reason) { await this.client.rest.post(Routes.guildMFA(this.id), { @@ -1177,7 +1183,7 @@ class Guild extends AnonymousGuild { * @example * // Leave a guild * guild.leave() - * .then(g => console.log(`Left the guild ${g}`)) + * .then(guild => console.log(`Left the guild: ${guild.name}`)) * .catch(console.error); */ async leave() { diff --git a/packages/discord.js/src/structures/GuildMember.js b/packages/discord.js/src/structures/GuildMember.js index f6d10d1f3e2f..8573b738df61 100644 --- a/packages/discord.js/src/structures/GuildMember.js +++ b/packages/discord.js/src/structures/GuildMember.js @@ -320,6 +320,11 @@ class GuildMember extends Base { * Edits this member. * @param {GuildMemberEditOptions} options The options to provide * @returns {Promise} + * @example + * // Deafen a guild member + * guildMember.edit({ deaf: true }) + * .then(member => console.log(`Deafened ${member.nickname}`)) + * .catch(console.log); */ edit(options) { return this.guild.members.edit(this, options); @@ -340,6 +345,11 @@ class GuildMember extends Base { * @param {?string} nick The nickname for the guild member, or `null` if you want to reset their nickname * @param {string} [reason] Reason for setting the nickname * @returns {Promise} + * @example + * // Set a nickname for a guild member + * guildMember.setNickname(null, "No nicknames allowed!") + * .then(member => console.log(`Removed nickname for ${member.user.username}`)) + * .catch(console.log); */ setNickname(nick, reason) { return this.edit({ nick, reason }); @@ -396,6 +406,11 @@ class GuildMember extends Base { * guildMember.disableCommunicationUntil(Date.now() + (5 * 60 * 1000), 'They deserved it') * .then(console.log) * .catch(console.error); + * @example + * // Remove the timeout of a guild member + * guildMember.disableCommunicationUntil(null) + * .then(member => `Removed timeout for ${member.nickname}`) + * .catch(console.error); */ disableCommunicationUntil(communicationDisabledUntil, reason) { return this.edit({ communicationDisabledUntil, reason }); diff --git a/packages/discord.js/src/structures/Message.js b/packages/discord.js/src/structures/Message.js index 407ede4f3fd8..e25b73f9ce4b 100644 --- a/packages/discord.js/src/structures/Message.js +++ b/packages/discord.js/src/structures/Message.js @@ -674,6 +674,11 @@ class Message extends Base { /** * Fetches the Message this crosspost/reply/pin-add references, if available to the client * @returns {Promise} + * @example + * // Fetch the reference of this message + * message.fetchReference() + * .then(reference => console.log(`Fetched the reference of this message: ${reference.content}`)) + * .catch(console.error); */ async fetchReference() { if (!this.reference) throw new DiscordjsError(ErrorCodes.MessageReferenceMissing); diff --git a/packages/discord.js/src/structures/Role.js b/packages/discord.js/src/structures/Role.js index 35526c1c44ad..0e18214046ae 100644 --- a/packages/discord.js/src/structures/Role.js +++ b/packages/discord.js/src/structures/Role.js @@ -193,6 +193,10 @@ class Role extends Base { * @param {RoleResolvable} role Role to compare to this one * @returns {number} Negative number if this role's position is lower (other role's is higher), * positive number if this one is higher (other's is lower), 0 if equal + * * @example + * // Compare the position of a role to another + * const comparisation = comparedRole.comparePositionTo(roleToCompareTo) + * if (comparisation === 1) console.log(`${comparedRole.name} is higher than ${roleToCompareTo.name}`) */ comparePositionTo(role) { return this.guild.roles.comparePositions(this, role); diff --git a/packages/discord.js/src/structures/interfaces/InteractionResponses.js b/packages/discord.js/src/structures/interfaces/InteractionResponses.js index 636f7310e5ac..b18361394537 100644 --- a/packages/discord.js/src/structures/interfaces/InteractionResponses.js +++ b/packages/discord.js/src/structures/interfaces/InteractionResponses.js @@ -270,6 +270,7 @@ class InteractionResponses { /** * Collects a single modal submit interaction that passes the filter. * The Promise will reject if the time expires. + * Use the `showModal` method to show a modal to the user * @param {AwaitModalSubmitOptions} options Options to pass to the internal collector * @returns {Promise} * @example From e760a0c24ecefb03e89d903cfb45f5392e498845 Mon Sep 17 00:00:00 2001 From: Tetie Date: Sun, 19 Mar 2023 19:42:11 +0100 Subject: [PATCH 2/7] fix: fix grammar and syntax Co-authored-by: Jaw0r3k --- packages/discord.js/src/structures/Guild.js | 2 +- packages/discord.js/src/structures/GuildMember.js | 4 ++-- packages/discord.js/src/structures/Role.js | 2 +- .../src/structures/interfaces/InteractionResponses.js | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/discord.js/src/structures/Guild.js b/packages/discord.js/src/structures/Guild.js index 87eddcd9ecda..d9ad93925a3f 100644 --- a/packages/discord.js/src/structures/Guild.js +++ b/packages/discord.js/src/structures/Guild.js @@ -1157,7 +1157,7 @@ class Guild extends AnonymousGuild { /** * Sets the guild's MFA level - * An elevated MFA level requires guild moderators to have 2FA enabled + * An elevated MFA level requires guild moderators to have 2FA enabled. * @param {GuildMFALevel} level The MFA level * @param {string} [reason] Reason for changing the guild's MFA level * @returns {Promise} diff --git a/packages/discord.js/src/structures/GuildMember.js b/packages/discord.js/src/structures/GuildMember.js index 8573b738df61..51711869f83d 100644 --- a/packages/discord.js/src/structures/GuildMember.js +++ b/packages/discord.js/src/structures/GuildMember.js @@ -346,7 +346,7 @@ class GuildMember extends Base { * @param {string} [reason] Reason for setting the nickname * @returns {Promise} * @example - * // Set a nickname for a guild member + * // Remove a nickname for a guild member * guildMember.setNickname(null, "No nicknames allowed!") * .then(member => console.log(`Removed nickname for ${member.user.username}`)) * .catch(console.log); @@ -409,7 +409,7 @@ class GuildMember extends Base { * @example * // Remove the timeout of a guild member * guildMember.disableCommunicationUntil(null) - * .then(member => `Removed timeout for ${member.nickname}`) + * .then(member => `Removed timeout for ${member.displayName}`) * .catch(console.error); */ disableCommunicationUntil(communicationDisabledUntil, reason) { diff --git a/packages/discord.js/src/structures/Role.js b/packages/discord.js/src/structures/Role.js index 0e18214046ae..9f22b4a663ce 100644 --- a/packages/discord.js/src/structures/Role.js +++ b/packages/discord.js/src/structures/Role.js @@ -196,7 +196,7 @@ class Role extends Base { * * @example * // Compare the position of a role to another * const comparisation = comparedRole.comparePositionTo(roleToCompareTo) - * if (comparisation === 1) console.log(`${comparedRole.name} is higher than ${roleToCompareTo.name}`) + * if (comparisation >= 1) console.log(`${comparedRole.name} is higher than ${roleToCompareTo.name}`) */ comparePositionTo(role) { return this.guild.roles.comparePositions(this, role); diff --git a/packages/discord.js/src/structures/interfaces/InteractionResponses.js b/packages/discord.js/src/structures/interfaces/InteractionResponses.js index b18361394537..b2e554f59c77 100644 --- a/packages/discord.js/src/structures/interfaces/InteractionResponses.js +++ b/packages/discord.js/src/structures/interfaces/InteractionResponses.js @@ -270,7 +270,7 @@ class InteractionResponses { /** * Collects a single modal submit interaction that passes the filter. * The Promise will reject if the time expires. - * Use the `showModal` method to show a modal to the user + * Use the `showModal` method to show a modal to the user. * @param {AwaitModalSubmitOptions} options Options to pass to the internal collector * @returns {Promise} * @example From 6cdf80ad59d0ebcb4dc06d0bb9dbc2077e04e5dd Mon Sep 17 00:00:00 2001 From: TetieWasTaken Date: Mon, 20 Mar 2023 07:51:44 +0100 Subject: [PATCH 3/7] chore: fine-tune examples --- packages/discord.js/src/structures/GuildMember.js | 11 +++++------ packages/discord.js/src/structures/Message.js | 4 ---- packages/discord.js/src/structures/Role.js | 4 ++-- .../src/structures/interfaces/InteractionResponses.js | 1 - 4 files changed, 7 insertions(+), 13 deletions(-) diff --git a/packages/discord.js/src/structures/GuildMember.js b/packages/discord.js/src/structures/GuildMember.js index 51711869f83d..22f23fde31ee 100644 --- a/packages/discord.js/src/structures/GuildMember.js +++ b/packages/discord.js/src/structures/GuildMember.js @@ -320,11 +320,6 @@ class GuildMember extends Base { * Edits this member. * @param {GuildMemberEditOptions} options The options to provide * @returns {Promise} - * @example - * // Deafen a guild member - * guildMember.edit({ deaf: true }) - * .then(member => console.log(`Deafened ${member.nickname}`)) - * .catch(console.log); */ edit(options) { return this.guild.members.edit(this, options); @@ -346,10 +341,14 @@ class GuildMember extends Base { * @param {string} [reason] Reason for setting the nickname * @returns {Promise} * @example + * // Set a nickname for a guild member + * guildMember.setNickname("cool nickname", "Needed a new nickname") + * .then(member => console.log(`Set nickname of ${member.user.username}`)) + * .catch(console.error); * // Remove a nickname for a guild member * guildMember.setNickname(null, "No nicknames allowed!") * .then(member => console.log(`Removed nickname for ${member.user.username}`)) - * .catch(console.log); + * .catch(console.error); */ setNickname(nick, reason) { return this.edit({ nick, reason }); diff --git a/packages/discord.js/src/structures/Message.js b/packages/discord.js/src/structures/Message.js index e25b73f9ce4b..81be604f280b 100644 --- a/packages/discord.js/src/structures/Message.js +++ b/packages/discord.js/src/structures/Message.js @@ -675,10 +675,6 @@ class Message extends Base { * Fetches the Message this crosspost/reply/pin-add references, if available to the client * @returns {Promise} * @example - * // Fetch the reference of this message - * message.fetchReference() - * .then(reference => console.log(`Fetched the reference of this message: ${reference.content}`)) - * .catch(console.error); */ async fetchReference() { if (!this.reference) throw new DiscordjsError(ErrorCodes.MessageReferenceMissing); diff --git a/packages/discord.js/src/structures/Role.js b/packages/discord.js/src/structures/Role.js index 9f22b4a663ce..60ee3c5c7403 100644 --- a/packages/discord.js/src/structures/Role.js +++ b/packages/discord.js/src/structures/Role.js @@ -195,8 +195,8 @@ class Role extends Base { * positive number if this one is higher (other's is lower), 0 if equal * * @example * // Compare the position of a role to another - * const comparisation = comparedRole.comparePositionTo(roleToCompareTo) - * if (comparisation >= 1) console.log(`${comparedRole.name} is higher than ${roleToCompareTo.name}`) + * const roleCompare = role.comparePositionTo(otherRole); + * if (roleCompare === 1) console.log(`${role.name} is higher than ${otherRole.name}`); */ comparePositionTo(role) { return this.guild.roles.comparePositions(this, role); diff --git a/packages/discord.js/src/structures/interfaces/InteractionResponses.js b/packages/discord.js/src/structures/interfaces/InteractionResponses.js index b2e554f59c77..636f7310e5ac 100644 --- a/packages/discord.js/src/structures/interfaces/InteractionResponses.js +++ b/packages/discord.js/src/structures/interfaces/InteractionResponses.js @@ -270,7 +270,6 @@ class InteractionResponses { /** * Collects a single modal submit interaction that passes the filter. * The Promise will reject if the time expires. - * Use the `showModal` method to show a modal to the user. * @param {AwaitModalSubmitOptions} options Options to pass to the internal collector * @returns {Promise} * @example From c71e45698f6788fd7b29af4b6114567c228820dd Mon Sep 17 00:00:00 2001 From: TetieWasTaken Date: Mon, 20 Mar 2023 07:54:48 +0100 Subject: [PATCH 4/7] chore: replace double quotes with singles --- packages/discord.js/src/structures/GuildMember.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/discord.js/src/structures/GuildMember.js b/packages/discord.js/src/structures/GuildMember.js index 22f23fde31ee..2fbc76cdce04 100644 --- a/packages/discord.js/src/structures/GuildMember.js +++ b/packages/discord.js/src/structures/GuildMember.js @@ -342,11 +342,11 @@ class GuildMember extends Base { * @returns {Promise} * @example * // Set a nickname for a guild member - * guildMember.setNickname("cool nickname", "Needed a new nickname") + * guildMember.setNickname('cool nickname', 'Needed a new nickname') * .then(member => console.log(`Set nickname of ${member.user.username}`)) * .catch(console.error); * // Remove a nickname for a guild member - * guildMember.setNickname(null, "No nicknames allowed!") + * guildMember.setNickname(null, 'No nicknames allowed!') * .then(member => console.log(`Removed nickname for ${member.user.username}`)) * .catch(console.error); */ From a0cf7fe91de7ace8e2676f469037968469ff8d29 Mon Sep 17 00:00:00 2001 From: TetieWasTaken Date: Mon, 20 Mar 2023 07:56:06 +0100 Subject: [PATCH 5/7] fix: remove redundant example tag --- packages/discord.js/src/structures/Message.js | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/discord.js/src/structures/Message.js b/packages/discord.js/src/structures/Message.js index 81be604f280b..407ede4f3fd8 100644 --- a/packages/discord.js/src/structures/Message.js +++ b/packages/discord.js/src/structures/Message.js @@ -674,7 +674,6 @@ class Message extends Base { /** * Fetches the Message this crosspost/reply/pin-add references, if available to the client * @returns {Promise} - * @example */ async fetchReference() { if (!this.reference) throw new DiscordjsError(ErrorCodes.MessageReferenceMissing); From 686bf6288616866787bc92ddee1fd1664d1f1c44 Mon Sep 17 00:00:00 2001 From: TetieWasTaken Date: Mon, 20 Mar 2023 22:19:05 +0100 Subject: [PATCH 6/7] fix: fix timeout logging --- packages/discord.js/src/structures/GuildMember.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/discord.js/src/structures/GuildMember.js b/packages/discord.js/src/structures/GuildMember.js index 2fbc76cdce04..a721acf73bc8 100644 --- a/packages/discord.js/src/structures/GuildMember.js +++ b/packages/discord.js/src/structures/GuildMember.js @@ -408,7 +408,7 @@ class GuildMember extends Base { * @example * // Remove the timeout of a guild member * guildMember.disableCommunicationUntil(null) - * .then(member => `Removed timeout for ${member.displayName}`) + * .then(member => console.log(`Removed timeout for ${member.displayName}`)) * .catch(console.error); */ disableCommunicationUntil(communicationDisabledUntil, reason) { From 650988dede36a31cd0e474f07a2c62b19374a0f9 Mon Sep 17 00:00:00 2001 From: Vlad Frangu Date: Wed, 22 Mar 2023 20:59:46 +0200 Subject: [PATCH 7/7] Update packages/discord.js/src/structures/GuildMember.js Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com> --- packages/discord.js/src/structures/GuildMember.js | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/discord.js/src/structures/GuildMember.js b/packages/discord.js/src/structures/GuildMember.js index a721acf73bc8..f56b5e342c4d 100644 --- a/packages/discord.js/src/structures/GuildMember.js +++ b/packages/discord.js/src/structures/GuildMember.js @@ -345,6 +345,7 @@ class GuildMember extends Base { * guildMember.setNickname('cool nickname', 'Needed a new nickname') * .then(member => console.log(`Set nickname of ${member.user.username}`)) * .catch(console.error); + * @example * // Remove a nickname for a guild member * guildMember.setNickname(null, 'No nicknames allowed!') * .then(member => console.log(`Removed nickname for ${member.user.username}`))