From bf507ab2659d95e2991e83293b3834f21283ff33 Mon Sep 17 00:00:00 2001
From: Tetie <tjvssr@gmail.com>
Date: Wed, 22 Mar 2023 20:09:41 +0100
Subject: [PATCH] docs: add more examples (#9252)

* docs: add more examples

* fix: fix grammar and syntax

Co-authored-by: Jaw0r3k <jaworekwiadomosci@gmail.com>

* chore: fine-tune examples

* chore: replace double quotes with singles

* fix: remove redundant example tag

* fix: fix timeout logging

* Update packages/discord.js/src/structures/GuildMember.js

Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com>

---------

Co-authored-by: Jaw0r3k <jaworekwiadomosci@gmail.com>
Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>
Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
---
 packages/discord.js/src/structures/Guild.js       |  8 +++++++-
 packages/discord.js/src/structures/GuildMember.js | 15 +++++++++++++++
 packages/discord.js/src/structures/Role.js        |  4 ++++
 3 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/discord.js/src/structures/Guild.js b/packages/discord.js/src/structures/Guild.js
index 4799d5db3..d9ad93925 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
+   * <info>An elevated MFA level requires guild moderators to have 2FA enabled.</info>
    * @param {GuildMFALevel} level The MFA level
    * @param {string} [reason] Reason for changing the guild's MFA level
    * @returns {Promise<Guild>}
+   * @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 f6d10d1f3..f56b5e342 100644
--- a/packages/discord.js/src/structures/GuildMember.js
+++ b/packages/discord.js/src/structures/GuildMember.js
@@ -340,6 +340,16 @@ 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<GuildMember>}
+   * @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);
+   * @example
+   * // 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.error);
    */
   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 => console.log(`Removed timeout for ${member.displayName}`))
+   *   .catch(console.error);
    */
   disableCommunicationUntil(communicationDisabledUntil, reason) {
     return this.edit({ communicationDisabledUntil, reason });
diff --git a/packages/discord.js/src/structures/Role.js b/packages/discord.js/src/structures/Role.js
index 35526c1c4..60ee3c5c7 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 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);