docs: improve examples (#2200)

* docs: improve examples


another

* remove conflict

* some nuances

* backport

src/structures/Channel.js

@@ -58,8 +58,8 @@ class Channel {
    * @example
    * // Delete the channel
    * channel.delete()
-   *   .then() // Success
+   *   .then(console.log)
-   *   .catch(console.error); // Log error
+   *   .catch(console.error);
    */
   delete() {
     return this.client.rest.methods.deleteChannel(this);

src/structures/Guild.js

@@ -486,6 +486,11 @@ class Guild {
    * @param {UserResolvable} [options.user] Only show entries involving this user
    * @param {string|number} [options.type] Only show entries involving this action type
    * @returns {Promise<GuildAuditLogs>}
+   * @example
+   * // Output audit log entries
+   * guild.fetchAuditLogs()
+   *   .then(audit => console.log(audit.entries))
+   *   .catch(console.error);
    */
   fetchAuditLogs(options) {
     return this.client.rest.methods.getGuildAuditLogs(this, options);
@@ -514,6 +519,11 @@ class Guild {
    * @param {UserResolvable} user The user to fetch the member for
    * @param {boolean} [cache=true] Insert the member into the members cache
    * @returns {Promise<GuildMember>}
+   * @example
+   * // Fetch a guild member
+   * guild.fetchMember(message.author)
+   *   .then(console.log)
+   *   .catch(console.error);
    */
   fetchMember(user, cache = true) {
     user = this.client.resolver.resolveUser(user);

src/structures/GuildChannel.js

@@ -223,8 +223,8 @@ class GuildChannel extends Channel {
    * @returns {Promise<GuildChannel>}
    * @example
    * // Edit a channel
-   * channel.edit({name: 'new-channel'})
+   * channel.edit({ name: 'new-channel' })
-   *   .then(c => console.log(`Edited channel ${c}`))
+   *   .then(console.log)
    *   .catch(console.error);
    */
   edit(data, reason) {
@@ -298,6 +298,11 @@ class GuildChannel extends Channel {
    * @param {boolean} [options.unique=false] Create a unique invite, or use an existing one with similar settings
    * @param {string} [reason] Reason for creating the invite
    * @returns {Promise<Invite>}
+   * @example
+   * // Create an invite to a channel
+   * channel.createInvite()
+   *   .then(invite => console.log(`Created an invite with a code of ${invite.code}`))
+   *   .catch(console.error);
    */
   createInvite(options = {}, reason) {
     return this.client.rest.methods.createChannelInvite(this, options, reason);

src/structures/GuildMember.js

@@ -386,6 +386,16 @@ class GuildMember {
    * @param {Collection<Snowflake, Role>|Role[]|Snowflake[]} roles The roles or role IDs to apply
    * @param {string} [reason] Reason for applying the roles
    * @returns {Promise<GuildMember>}
+   * @example
+   * // Set the member's roles to a single role
+   * guildMember.setRoles(['391156570408615936'])
+   *   .then(console.log)
+   *   .catch(console.error);
+   * @example
+   * // Remove all the roles from a member
+   * guildMember.setRoles([])
+   *   .then(member => console.log(`Member roles is now of ${member.roles.size} size`))
+   *   .catch(console.error);
    */
   setRoles(roles, reason) {
     return this.edit({ roles }, reason);
@@ -497,8 +507,10 @@ class GuildMember {
    * @param {string} [options.reason] Reason for banning
    * @returns {Promise<GuildMember>}
    * @example
-   * // ban a guild member
+   * // Ban a guild member
-   * guildMember.ban(7);
+   * guildMember.ban(7)
+   *   .then(console.log)
+   *   .catch(console.error);
    */
   ban(options) {
     return this.guild.ban(this, options);

src/structures/Message.js

@@ -254,10 +254,8 @@ class Message {
    * @returns {ReactionCollector}
    * @example
    * // Create a reaction collector
-   * const collector = message.createReactionCollector(
+   * const filter = (reaction, user) => reaction.emoji.name === '👌' && user.id === 'someID'
-   *   (reaction, user) => reaction.emoji.name === '👌' && user.id === 'someID',
+   * const collector = message.createReactionCollector(filter, { time: 15000 });
-   *   { time: 15000 }
-   * );
    * collector.on('collect', r => console.log(`Collected ${r.emoji.name}`));
    * collector.on('end', collected => console.log(`Collected ${collected.size} items`));
    */
@@ -277,6 +275,12 @@ class Message {
    * @param {CollectorFilter} filter The filter function to use
    * @param {AwaitReactionsOptions} [options={}] Optional options to pass to the internal collector
    * @returns {Promise<Collection<string, MessageReaction>>}
+   * @example
+   * // Create a reaction collector
+   * const filter = (reaction, user) => reaction.emoji.name === '👌' && user.id === 'someID'
+   * message.awaitReactions(filter, { time: 15000 })
+   *   .then(collected => console.log(`Collected ${collected.size} reactions`))
+   *   .catch(console.error);
    */
   awaitReactions(filter, options = {}) {
     return new Promise((resolve, reject) => {

src/structures/interfaces/TextBasedChannel.js

@@ -171,7 +171,7 @@ class TextBasedChannel {
    * @returns {Promise<Collection<Snowflake, Message>>}
    * @example
    * // Get messages
-   * channel.fetchMessages({limit: 10})
+   * channel.fetchMessages({ limit: 10 })
    *   .then(messages => console.log(`Received ${messages.size} messages`))
    *   .catch(console.error);
    */
@@ -303,7 +303,7 @@ class TextBasedChannel {
    * <info>It can take a few seconds for the client user to stop typing.</info>
    * @param {boolean} [force=false] Whether or not to reset the call count and force the indicator to stop
    * @example
-   * // Stop typing in a channel
+   * // Reduce the typing count by one and stop typing if it reached 0
    * channel.stopTyping();
    * @example
    * // Force typing to fully stop in a channel
@@ -357,10 +357,8 @@ class TextBasedChannel {
    * @returns {MessageCollector}
    * @example
    * // Create a message collector
-   * const collector = channel.createMessageCollector(
+   * const filter = m => m.content.includes('discord');
-   *   m => m.content.includes('discord'),
+   * const collector = channel.createMessageCollector(filter, { time: 15000 });
-   *   { time: 15000 }
-   * );
    * collector.on('collect', m => console.log(`Collected ${m.content}`));
    * collector.on('end', collected => console.log(`Collected ${collected.size} items`));
    */
@@ -407,6 +405,11 @@ class TextBasedChannel {
    * @param {Collection<Snowflake, Message>|Message[]|number} messages Messages or number of messages to delete
    * @param {boolean} [filterOld=false] Filter messages to remove those which are older than two weeks automatically
    * @returns {Promise<Collection<Snowflake, Message>>} Deleted messages
+   * @example
+   * // Bulk delete messages
+   * channel.bulkDelete(5)
+   *   .then(messages => console.log(`Bulk deleted ${messages.size} messages`))
+   *   .catch(console.error);
    */
   bulkDelete(messages, filterOld = false) {
     if (messages instanceof Array || messages instanceof Collection) {