Documentation improvements (#2069)

* docs: fix documentation in various places

All stores: resolveID returns a nullable Snowflake
GuildAuditLogs: ActionType also can be ALL
MessageEmbed: make files property show up in the docs
ClientApplication: resetSecret and resetToken return a promise
ClientManager: status is readonly
Guild: features is an array of strings and ban no longer accepts a number or string
Guild: ban method no longer accepts a string or number
GuildMember: ^
RichPresenceAssets: small and large Image are Snowflakes, also fixed parameter documentation for small and large image url method
WebhookMessageOptions: file property is no longer a thing

* docs: improve GuildAuditLogs documentation

Prefix types with AuditLog to avoid confusion
Document GuildAuditLogs' static Targets and Actions properties and add necessary typedefs
Use typdefs over primitives where possible.

* fix documentation for Guild#defaultRole

src/client/ClientManager.js

@@ -22,6 +22,7 @@ class ClientManager {
 
   /**
    * The status of the client
+   * @readonly
    * @type {number}
    */
   get status() {

src/stores/ChannelStore.js

@@ -95,7 +95,7 @@ class ChannelStore extends DataStore {
    * @memberof ChannelStore
    * @instance
    * @param {ChannelResolvable} channel The channel resolvable to resolve
-   * @returns {?string}
+   * @returns {?Snowflake}
    */
 }
 

src/stores/DataStore.js

@@ -37,7 +37,7 @@ class DataStore extends Collection {
   /**
    * Resolves a data entry to a instance ID.
    * @param {string|Instance} idOrInstance The id or instance of something in this DataStore
-   * @returns {?string}
+   * @returns {?Snowflake}
    */
   resolveID(idOrInstance) {
     if (idOrInstance instanceof this.holds) return idOrInstance.id;

src/stores/EmojiStore.js

@@ -38,7 +38,7 @@ class EmojiStore extends DataStore {
   /**
    * Resolves a EmojiResolvable to a Emoji ID string.
    * @param {EmojiResolvable} emoji The Emoji resolvable to identify
-   * @returns {?string}
+   * @returns {?Snowflake}
    */
   resolveID(emoji) {
     if (emoji instanceof ReactionEmoji) return emoji.id;

src/stores/GuildChannelStore.js

@@ -42,7 +42,7 @@ class GuildChannelStore extends DataStore {
    * @memberof GuildChannelStore
    * @instance
    * @param {GuildChannelResolvable} channel The GuildChannel resolvable to resolve
-   * @returns {?string}
+   * @returns {?Snowflake}
    */
 }
 

src/stores/GuildMemberStore.js

@@ -41,7 +41,7 @@ class GuildMemberStore extends DataStore {
   /**
    * Resolves a GuildMemberResolvable to an member ID string.
    * @param {GuildMemberResolvable} member The user that is part of the guild
-   * @returns {?string}
+   * @returns {?Snowflake}
    */
   resolveID(member) {
     const memberResolveable = super.resolveID(member);

src/stores/GuildStore.js

@@ -33,7 +33,7 @@ class GuildStore extends DataStore {
    * @memberof GuildStore
    * @instance
    * @param {GuildResolvable} guild The guild resolvable to identify
-   * @returns {?string}
+   * @returns {?Snowflake}
    */
 }
 

src/stores/MessageStore.js

@@ -112,7 +112,7 @@ class MessageStore extends DataStore {
     * @memberof MessageStore
     * @instance
     * @param {MessageResolvable} message The message resolvable to resolve
-    * @returns {?string}
+    * @returns {?Snowflake}
     */
 }
 

src/stores/PresenceStore.js

@@ -39,7 +39,7 @@ class PresenceStore extends DataStore {
   /**
     * Resolves a PresenceResolvable to a Presence ID string.
     * @param {PresenceResolvable} presence The presence resolvable to resolve
-    * @returns {?string}
+    * @returns {?Snowflake}
     */
   resolveID(presence) {
     const presenceResolveable = super.resolveID(presence);

src/stores/ReactionStore.js

@@ -38,7 +38,7 @@ class ReactionStore extends DataStore {
     * @memberof ReactionStore
     * @instance
     * @param {MessageReactionResolvable} role The role resolvable to resolve
-    * @returns {?string}
+    * @returns {?Snowflake}
     */
 }
 

src/stores/RoleStore.js

@@ -38,7 +38,7 @@ class RoleStore extends DataStore {
     * @memberof RoleStore
     * @instance
     * @param {RoleResolvable} role The role resolvable to resolve
-    * @returns {?string}
+    * @returns {?Snowflake}
     */
 }
 

src/stores/UserStore.js

@@ -35,7 +35,7 @@ class UserStore extends DataStore {
   /**
    * Resolves a UserResolvable to a user ID string.
    * @param {UserResolvable} user The UserResolvable to identify
-   * @returns {?string}
+   * @returns {?Snowflake}
    */
   resolveID(user) {
     if (user instanceof GuildMember) return user.user.id;

src/structures/ClientApplication.js

@@ -177,7 +177,7 @@ class ClientApplication extends Base {
   /**
    * Resets the app's secret.
    * <warn>This is only available when using a user account.</warn>
-   * @returns {ClientApplication}
+   * @returns {Promise<ClientApplication>}
    */
   resetSecret() {
     return this.client.api.oauth2.applications[this.id].reset.post()
@@ -187,7 +187,7 @@ class ClientApplication extends Base {
   /**
    * Resets the app's bot token.
    * <warn>This is only available when using a user account.</warn>
-   * @returns {ClientApplication}
+   * @returns {Promise<ClientApplication>}
    */
   resetToken() {
     return this.client.api.oauth2.applications[this.id].bot.reset.post()

src/structures/Guild.js

@@ -115,7 +115,7 @@ class Guild extends Base {
 
     /**
      * An array of guild features
-     * @type {Object[]}
+     * @type {string[]}
      */
     this.features = data.features;
 
@@ -401,7 +401,7 @@ class Guild extends Base {
     }
   }
 
-  /*
+  /**
    * The `@everyone` role of the guild
    * @type {Role}
    * @readonly
@@ -802,7 +802,7 @@ class Guild extends Base {
   /**
    * Bans a user from the guild.
    * @param {UserResolvable} user The user to ban
-   * @param {Object|number|string} [options] Ban options. If a number, the number of days to delete messages for, if a
+   * @param {Object} [options] Ban options. If a number, the number of days to delete messages for, if a
    * string, the ban reason. Supplying an object allows you to do both.
    * @param {number} [options.days=0] Number of days of messages to delete
    * @param {string} [options.reason] Reason for banning

src/structures/GuildAuditLogs.js

@@ -2,6 +2,24 @@ const Collection = require('../util/Collection');
 const Snowflake = require('../util/Snowflake');
 const Webhook = require('./Webhook');
 
+/**
+ * The target type of an entry, e.g. `GUILD`. Here are the available types:
+ * * GUILD
+ * * CHANNEL
+ * * USER
+ * * ROLE
+ * * INVITE
+ * * WEBHOOK
+ * * EMOJI
+ * * MESSAGE
+ * @typedef {string} AuditLogTargetType
+ */
+
+/**
+ * Key mirror of all available audit log targets.
+ * @name GuildAuditLogs.Targets
+ * @type {AuditLogTargetType}
+ */
 const Targets = {
   ALL: 'ALL',
   GUILD: 'GUILD',
@@ -15,6 +33,43 @@ const Targets = {
   UNKNOWN: 'UNKNOWN',
 };
 
+/**
+ * The action of an entry. Here are the available actions:
+ * * ALL: null
+ * * GUILD_UPDATE: 1
+ * * CHANNEL_CREATE: 10
+ * * CHANNEL_UPDATE: 11
+ * * CHANNEL_DELETE: 12
+ * * CHANNEL_OVERWRITE_CREATE: 13
+ * * CHANNEL_OVERWRITE_UPDATE: 14
+ * * CHANNEL_OVERWRITE_DELETE: 15
+ * * MEMBER_KICK: 20
+ * * MEMBER_PRUNE: 21
+ * * MEMBER_BAN_ADD: 22
+ * * MEMBER_BAN_REMOVE: 23
+ * * MEMBER_UPDATE: 24
+ * * MEMBER_ROLE_UPDATE: 25
+ * * ROLE_CREATE: 30
+ * * ROLE_UPDATE: 31
+ * * ROLE_DELETE: 32
+ * * INVITE_CREATE: 40
+ * * INVITE_UPDATE: 41
+ * * INVITE_DELETE: 42
+ * * WEBHOOK_CREATE: 50
+ * * WEBHOOK_UPDATE: 51
+ * * WEBHOOK_DELETE: 50
+ * * EMOJI_CREATE: 60
+ * * EMOJI_UPDATE: 61
+ * * EMOJI_DELETE: 62
+ * * MESSAGE_DELETE: 72
+ * @typedef {?number|string} AuditLogAction
+ */
+
+/**
+ * All available actions keyed under their names to their numeric values.
+ * @name GuildAuditLogs.Actions
+ * @type {AuditLogAction}
+ */
 const Actions = {
   ALL: null,
   GUILD_UPDATE: 1,
@@ -85,20 +140,7 @@ class GuildAuditLogs {
   }
 
   /**
-   * The target type of an entry, e.g. `GUILD`. Here are the available types:
-   * * GUILD
-   * * CHANNEL
-   * * USER
-   * * ROLE
-   * * INVITE
-   * * WEBHOOK
-   * * EMOJI
-   * * MESSAGE
-   * @typedef {string} TargetType
-   */
-
-  /**
-   * The target for an audit log entry. It can be one of:
+   * The target of an entry. It can be one of:
    * * A guild
    * * A user
    * * A role
@@ -106,13 +148,13 @@ class GuildAuditLogs {
    * * An invite
    * * A webhook
    * * An object where the keys represent either the new value or the old value
-   * @typedef {?Object|Guild|User|Role|Emoji|Invite|Webhook} EntryTarget
+   * @typedef {?Object|Guild|User|Role|Emoji|Invite|Webhook} AuditLogEntryTarget
    */
 
   /**
    * Finds the target type from the entry action.
-   * @param {number} target The action target
-   * @returns {?string}
+   * @param {AuditLogAction} target The action target
+   * @returns {AuditLogTargetType}
    */
   static targetType(target) {
     if (target < 10) return Targets.GUILD;
@@ -131,13 +173,14 @@ class GuildAuditLogs {
    * * CREATE
    * * DELETE
    * * UPDATE
-   * @typedef {string} ActionType
+   * * ALL
+   * @typedef {string} AuditLogActionType
    */
 
   /**
    * Finds the action type from the entry action.
-   * @param {string} action The action target
-   * @returns {string}
+   * @param {AuditLogAction} action The action target
+   * @returns {AuditLogActionType}
    */
   static actionType(action) {
     if ([
@@ -187,19 +230,19 @@ class GuildAuditLogsEntry {
     const targetType = GuildAuditLogs.targetType(data.action_type);
     /**
      * The target type of this entry
-     * @type {TargetType}
+     * @type {AuditLogTargetType}
      */
     this.targetType = targetType;
 
     /**
      * The action type of this entry
-     * @type {ActionType}
+     * @type {AuditLogActionType}
      */
     this.actionType = GuildAuditLogs.actionType(data.action_type);
 
     /**
-     * Specific action type of this entry
-     * @type {string}
+     * Specific action type of this entry in its string presentation
+     * @type {AuditLogAction}
      */
     this.action = Object.keys(Actions).find(k => Actions[k] === data.action_type);
 
@@ -271,7 +314,7 @@ class GuildAuditLogsEntry {
     if (targetType === Targets.UNKNOWN) {
       /**
        * The target of this entry
-       * @type {EntryTarget}
+       * @type {AuditLogEntryTarget}
        */
       this.target = this.changes.reduce((o, c) => {
         o[c.key] = c.new || c.old;

src/structures/GuildMember.js

@@ -515,7 +515,7 @@ class GuildMember extends Base {
 
   /**
    * Bans this guild member.
-   * @param {Object|number|string} [options] Ban options. If a number, the number of days to delete messages for, if a
+   * @param {Object} [options] Ban options. If a number, the number of days to delete messages for, if a
    * string, the ban reason. Supplying an object allows you to do both.
    * @param {number} [options.days=0] Number of days of messages to delete
    * @param {string} [options.reason] Reason for banning

src/structures/MessageEmbed.js

@@ -132,12 +132,12 @@ class MessageEmbed {
       proxyIconURL: data.footer.proxyIconURL || data.footer.proxy_icon_url,
     } : null;
 
-    /**
-     * The files of this embed
-     * @type {?Object}
-     * @property {Array<FileOptions|string|MessageAttachment>} files Files to attach
-     */
     if (data.files) {
+      /**
+       * The files of this embed
+       * @type {?Object}
+       * @property {Array<FileOptions|string|MessageAttachment>} files Files to attach
+       */
       this.files = data.files.map(file => {
         if (file instanceof MessageAttachment) {
           return typeof file.file === 'string' ? file.file : Util.cloneObject(file.file);
@@ -158,7 +158,7 @@ class MessageEmbed {
 
   /**
    * The hexadecimal version of the embed color, with a leading hash
-   * @type {string}
+   * @type {?string}
    * @readonly
    */
   get hexColor() {

src/structures/Presence.js

@@ -160,21 +160,22 @@ class RichPresenceAssets {
 
     /**
      * ID of the large image asset
-     * @type {?string}
+     * @type {?Snowflake}
      */
     this.largeImage = assets.large_image || null;
 
     /**
      * ID of the small image asset
-     * @type {?string}
+     * @type {?Snowflake}
      */
     this.smallImage = assets.small_image || null;
   }
 
   /**
    * Gets the URL of the small image asset
-   * @param  {string} format Format of the image
-   * @param  {number} size Size of the image
+   * @param {Object} [options] Options for the image url
+   * @param {string} [options.format] Format of the image
+   * @param {number} [options.size] Size of the image
    * @returns {?string} The small image URL
    */
   smallImageURL({ format, size } = {}) {
@@ -185,8 +186,9 @@ class RichPresenceAssets {
 
   /**
    * Gets the URL of the large image asset
-   * @param  {string} format Format of the image
-   * @param  {number} size Size of the image
+   * @param {Object} [options] Options for the image url
+   * @param {string} [options.format] Format of the image
+   * @param {number} [options.size] Size of the image
    * @returns {?string} The large image URL
    */
   largeImageURL({ format, size } = {}) {

src/structures/Webhook.js

@@ -79,7 +79,6 @@ class Webhook {
    * (see [here](https://discordapp.com/developers/docs/resources/channel#embed-object) for more details)
    * @property {boolean} [disableEveryone=this.client.options.disableEveryone] Whether or not @everyone and @here
    * should be replaced with plain-text
-   * @property {FileOptions|BufferResolvable} [file] A file to send with the message
    * @property {FileOptions[]|string[]} [files] Files to send with the message
    * @property {string|boolean} [code] Language for optional codeblock formatting to apply
    * @property {boolean|SplitOptions} [split=false] Whether or not the message should be split into multiple messages if