a lot of changes to documentation (#465)

* document paused property * node twitch.tv urls in setStreaming, added note on autoReconnect in troubleshooting * Fix improper formatting in Cache.get (#1) * Fix grammar in unpinMessage * Enhance troubleshooting (#2) * Enhance troubleshooting * getChannelLogs can take resolvables * Include variables * Add shortcuts * Add references to shortcuts * Add shortcuts for User * Add references for User * _
2026-03-09 16:13:31 +01:00 · 2016-07-13 21:05:54 -04:00
parent 45d61f24db
commit 422fffdbfb
12 changed files with 386 additions and 10 deletions
--- a/docs/docs_cache.rst
+++ b/docs/docs_cache.rst
@@ -26,6 +26,7 @@ get(key, value)
 Returns a contained object where ``object[key] == value``. Also works if value is a regex or a function. Returns the first object found that matches the criteria.

 get(value)
+~~~~~~~~~~

 Returns a contained object where ``object["id"] == value``. Shorthand for ``get("id", value)``. Returns ``null`` if ID is not found.

--- a/docs/docs_client.rst
+++ b/docs/docs_client.rst
@@ -300,7 +300,7 @@ getChannelLogs(channel, `limit`, `options`, `callback`)

 Gets a list of previously sent messages in a channel.

- **channel** - The Channel_ to get messages from
+- **channel** - A `Channel Resolvable`_ to get messages from
 - **limit** - The maximum amount of messages to retrieve - defaults to 50. A `Number`
 - **options** - An `object` containing either of the following:
    - **before** - A `Message Resolvable`_ - gets messages before this message.
@@ -333,7 +333,7 @@ Pins a message to a channel.
 unpinMessage(message, `callback`)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Unpins a message to a channel.
+Unpins a message from a channel.

 - **message** - The Message_ to unpin.
 - **callback** - `function` taking the following:
@@ -561,7 +561,7 @@ setStreaming(name, url, type, `callback`)
 Sets the Discord Status of the Client

 - **name** - `String`, Name of game being played
- **url** - `String`, URL that it will link to
+- **url** - `String`, URL that it will link to, only supports `twitch.tv` urls at this time.
 - **type** - `Number`, `1` indicates streaming
 - **callback** - `function` taking the following:
    - **error** - error if any occurred
--- a/docs/docs_invite.rst
+++ b/docs/docs_invite.rst
@@ -63,4 +63,29 @@ User_ who sent/created the invite.
 xkcd
 ~~~~

-`Boolean`, whether the invite is intended to be easy to read and remember by a human.
+`Boolean`, whether the invite is intended to be easy to read and remember by a human.
+
+--------
+
+Functions
+---------
+
+toString()
+~~~~~~~~~~
+
+Returns the invite URL.
+
+delete(`callback`)
+~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.deleteInvite(invite, callback)``
+| **See** client.deleteInvite_
+
+join(`callback`)
+~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.joinServer(invite, callback)``
+| **See** client.joinServer_
+
+.. _client.deleteInvite : ./docs_client.html#deleteinvite-invite-callback
+.. _client.joinServer : ./docs_client.html#joinserver-invite-callback
--- a/docs/docs_message.rst
+++ b/docs/docs_message.rst
@@ -98,3 +98,52 @@ isMentioned(user)
 Returns true if the given user was mentioned in the message.

 - **user** - A `User Resolvable`_
+
+toString()
+~~~~~~~~~~
+
+Returns the content of the Message.
+
+delete(`options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.deleteMessage(message, options, callback``
+| **See** client.deleteMessage_
+
+update(content, `options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.updateMessage(message, content, options, callback)``
+| **Aliases** `edit`
+| **See** client.updateMessage_
+
+reply(content, `options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.reply(message, content, options, callback)``
+| **See** client.reply_
+
+replyTTS(content, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.replyTTS(message, content, callback)``
+| **See** client.replyTTS_
+
+pin(`callback`)
+~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.pinMessage(message, callback)``
+| **See** client.pinMessage_
+
+unpin(`callback`)
+~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.unpinMessage(message, callback)``
+| **See** client.unpinMessage_
+
+.. _client.deleteMessage : ./docs_client.html#deletemessage-message-options-callback
+.. _client.updateMessage : ./docs_client.html#updatemessage-message-content-options-callback
+.. _client.reply : ./docs_client.html#reply-message-content-options-callback
+.. _client.replyTTS : ./docs_client.html#replytts-message-content-callback
+.. _client.pinMessage : ./docs_client.html#pinmessage-message-callback
+.. _client.unpinMessage : ./docs_client.html#unpinmessage-message-callback
--- a/docs/docs_pmchannel.rst
+++ b/docs/docs_pmchannel.rst
@@ -25,4 +25,66 @@ The User_ that is the recipient of the Channel.
 lastMessage
 ~~~~~~~~~~~

-The last Message_ sent in the channel, may be null if no messages have been sent during the time the bound Client_ has been online.
+The last Message_ sent in the channel, may be null if no messages have been sent during the time the bound Client_ has been online.
+
+--------
+
+Functions
+---------
+
+toString()
+~~~~~~~~~~
+
+Returns a mention of the recipient.
+
+sendMessage(content, `options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendMessage(channel, content, options, callback)``
+| **Aliases** `send`
+| **See** client.sendMessage_
+
+sendTTSMessage(content, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendTTSMessage(channel, content, callback)``
+| **Aliases** `sendTTS`
+| **See** client.sendTTSMessage_
+
+sendFile(attachment, name, content, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendFile(channel, attachment, name, content, callbasck)``
+| **See** client.sendFile_
+
+startTyping(`callback`)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.startTyping(channel, callback)``
+| **See** client.startTyping_
+
+stopTyping(`callback`)
+~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.stopTyping(channel, callback)``
+| **See** client.stopTyping_
+
+getLogs(`limit`, `options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.getChannelLogs(channel, limit, options, callback)``
+| **See** client.getChannelLogs_
+
+getMessage(messageID, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.getMessage(channel, messageID, callback)``
+| **See** client.getMessage_
+
+.. _client.sendMessage : ./docs_client.html#sendmessage-channel-content-options-callback
+.. _client.sendTTSMessage : ./docs_client.html#sendttsmessage-channel-content-callback
+.. _client.sendFile : ./docs_client.html#sendfile-channel-attachment-name-content-callback
+.. _client.startTyping : ./docs_client.html#starttyping-channel-callback
+.. _client.stopTyping : ./docs_client.html#stoptyping-channel-callback
+.. _client.getChannelLogs : ./docs_client.html#getchannellogs-channel-limit-options-callback
+.. _client.getMessage : ./docs_client.html#getmessage-channel-messageid-callback
--- a/docs/docs_role.rst
+++ b/docs/docs_role.rst
@@ -80,4 +80,36 @@ Returns the role's colour as hex, e.g. ``#FF0000``.
 mention()
 ~~~~~~~~~

-Returns a valid string that can be sent in a message to mention the role. By default, ``role.toString()`` does this so by adding a role object to a string, e.g. ``role + ""``, their mention code will be retrieved. If the role isn't mentionable, its name gets returned.
+Returns a valid string that can be sent in a message to mention the role. By default, ``role.toString()`` does this so by adding a role object to a string, e.g. ``role + ""``, their mention code will be retrieved. If the role isn't mentionable, its name gets returned.
+
+delete()
+~~~~~~~~
+
+| **Shortcut of** ``client.deleteRole(role)``
+| **See** client.deleteRole_
+
+update(data)
+~~~~~~~~~~~~
+
+| **Shortcut of** ``client.updateRole(role, data)``
+| **Aliases** `edit`
+| **See** client.updateRole_
+
+addMember(member, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.addMemberToRole(member, roles, callback)``
+| **Aliases** `addUser`
+| **See** client.addMemberToRole_
+
+removeMember(member, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.removeMemberFromRole(member, roles, callback)``
+| **Aliases** `removeUser`
+| **See** client.removeMemberFromRole_
+
+.. _client.deleteRole : ./docs_client.html#deleterole-role-callback
+.. _client.updateRole : ./docs_client.html#updaterole-role-data-callback
+.. _client.addMemberToRole : ./docs_client.html#addmembertorole-member-role-callback
+.. _client.removeMemberFromRole : ./docs_client.html#removememberfromrole-member-role-callback
--- a/docs/docs_textchannel.rst
+++ b/docs/docs_textchannel.rst
@@ -25,4 +25,75 @@ Last Message_ sent in the channel. May be null if no messages sent whilst the Cl
 messages
 ~~~~~~~~

-A Cache_ of Message_ objects.
+A Cache_ of Message_ objects.
+
+--------
+
+Functions
+---------
+
+setTopic(topic, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.setChannelTopic(channel, topic, callback)``
+| **See** client.setChannelTopic_
+
+setNameAndTopic(name, topic, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.setChannelNameAndTopic(channel, name, topic, callback)``
+| **See** client.setChannelNameAndTopic_
+
+sendMessage(content, `options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendMessage(channel, content, options, callback)``
+| **Aliases** `send`
+| **See** client.sendMessage_
+
+sendTTSMessage(content, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendTTSMessage(channel, content, callback)``
+| **Aliases** `sendTTS`
+| **See** client.sendTTSMessage_
+
+sendFile(attachment, name, content, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendFile(channel, attachment, name, content, callbasck)``
+| **See** client.sendFile_
+
+startTyping(`callback`)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.startTyping(channel, callback)``
+| **See** client.startTyping_
+
+stopTyping(`callback`)
+~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.stopTyping(channel, callback)``
+| **See** client.stopTyping
+
+getLogs(`limit`, `options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.getChannelLogs(channel, limit, options, callback)
+| **See** client.getChannelLogs_
+
+getMessage(messageID, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.getMessage(channel, messageID, callback)``
+| **See** client.getMessage_
+
+.. _client.sendMessage : ./docs_client.html#sendmessage-channel-content-options-callback
+.. _client.sendTTSMessage : ./docs_client.html#sendttsmessage-channel-content-callback
+.. _client.sendFile : ./docs_client.html#sendfile-channel-attachment-name-content-callback
+.. _client.startTyping : ./docs_client.html#starttyping-channel-callback
+.. _client.stopTyping : ./docs_client.html#stoptyping-channel-callback
+.. _client.getChannelLogs : ./docs_client.html#getchannellogs-channel-limit-options-callback
+.. _client.getMessage : ./docs_client.html#getmessage-channel-messageid-callback
+.. _client.setChannelTopic : ./docs_client.html#setchanneltopic-channel-topic-callback
+.. _client.setChannelNameAndTopic : ./docs_client.html#setchannelnameandtopic-channel-name-topic-callback
--- a/docs/docs_user.rst
+++ b/docs/docs_user.rst
@@ -103,4 +103,78 @@ Functions
 mention()
 ~~~~~~~~~

-Returns a valid string that can be sent in a message to mention the user. By default, ``user.toString()`` does this so by adding a user object to a string, e.g. ``user + ""``, their mention code will be retrieved.
+Returns a valid string that can be sent in a message to mention the user. By default, ``user.toString()`` does this so by adding a user object to a string, e.g. ``user + ""``, their mention code will be retrieved.
+
+sendMessage(content, `options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendMessage(channel, content, options, callback)``
+| **Aliases** `send`
+| **See** client.sendMessage_
+
+sendTTSMessage(content, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendTTSMessage(channel, content, callback)``
+| **Aliases** `sendTTS`
+| **See** client.sendTTSMessage_
+
+sendFile(attachment, name, content, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.sendFile(channel, attachment, name, content, callbasck)``
+| **See** client.sendFile_
+
+startTyping(`callback`)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.startTyping(channel, callback)``
+| **See** client.startTyping_
+
+stopTyping(`callback`)
+~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.stopTyping(channel, callback)``
+| **See** client.stopTyping_
+
+addTo(role, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.addMemberToRole(member, role, callback)``
+| **See** client.addMemberToRole_
+
+removeFrom(role, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.removeMemberFromRole(member, role, callback)``
+| **See** client.removeMemberFromRole_
+
+getLogs(`limit`, `options`, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.getChannelLogs(channel, limit, options, callback)``
+| **See** client.getChannelLogs_
+
+getMessage(messageID, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.getMessage(channel, messageID, callback)``
+| **See** client.getMessage_
+
+hasRole(role)
+~~~~~~~~~~~~
+
+| **Shortcut of** ``client.memberHasRole(member, role)``
+| **See** client.memberHasRole_
+
+
+.. _client.addMemberToRole : ./docs_client.html#addmembertorole-member-role-callback
+.. _client.removeMemberFromRole : ./docs_client.html#removememberfromrole-member-role-callback
+.. _client.memberHasRole : ./docs_client.html#memberhasrole-member-role
+.. _client.sendMessage : ./docs_client.html#sendmessage-channel-content-options-callback
+.. _client.sendTTSMessage : ./docs_client.html#sendttsmessage-channel-content-callback
+.. _client.sendFile : ./docs_client.html#sendfile-channel-attachment-name-content-callback
+.. _client.startTyping : ./docs_client.html#starttyping-channel-callback
+.. _client.stopTyping : ./docs_client.html#stoptyping-channel-callback
+.. _client.getChannelLogs : ./docs_client.html#getchannellogs-channel-limit-options-callback
+.. _client.getMessage : ./docs_client.html#getmessage-channel-messageid-callback
--- a/docs/docs_voicechannel.rst
+++ b/docs/docs_voicechannel.rst
@@ -35,4 +35,20 @@ setUserLimit(limit, `callback`)
 ~~~~~~~~~~~~~~~~~~~

 | **Shortcut of** ``client.setChannelUserLimit(channel, limit, callback)``
-| **See** client.setChannelUserLimit_
+| **See** client.setChannelUserLimit_
+
+setBitrate(kbitrate, `callback`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.setChannelBitrate(channel, kbitrate, callback)``
+| **See** client.setChannelBitrate_
+
+join(`callback`)
+~~~~~~~~~~~~~~~~~
+
+| **Shortcut of** ``client.joinVoiceChannel(channel, callback)``
+| **See** client.joinVoiceChannel_
+
+.. _client.setChannelUserLimit : ./docs_client.html#setchanneluserlimit-channel-limit-callback
+.. _client.setChannelBitrate : ./docs_client.html#setchannelbitrate-channel-bitrate-callback
+.. _client.getBans : ./docs_client.html#joinvoicechannel-channel-callback
--- a/docs/docs_voiceconnection.rst
+++ b/docs/docs_voiceconnection.rst
@@ -49,6 +49,11 @@ playing

 Whether or not the bot is currently playing something

+paused
+~~~~~~
+
+Whether or not the playback is currently paused
+
 streamTime
 ~~~~~~~~~~

--- a/docs/index.rst
+++ b/docs/index.rst
@@ -20,6 +20,7 @@ Feel free to make any contributions you want, whether it be through creating an

   installing
   migrating
+   troubleshooting

 .. toctree::
   :maxdepth: 1
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -1,11 +1,51 @@
+.. include:: ./vars.rst
+
 Troubleshooting
 ===============

+General
+-------
+
 Occasionally, the API can stop working for whatever reason. If it was working previously and it stopped working on the same version, it means that either we screwed code up or there's been a change to the Discord API. You can try asking around in the `discord.js channel in the API server`_. You could also `make an issue`_ if one relating to a similar issue doesn't exist. Please post a stacktrace if there is one, and be as detailed as possible - *"the API isn't working"* doesn't help at all.

 If there is already an issue, feel free to comment that you're also experiencing the same thing. This helps to see how widespread the bug is.

 You can try reconnecting before submitting an issue, as sometimes some of the servers may be slightly different.

+If you're your bot or client is exiting unexpectedly with no error, this is likely caused by websocket disconnects. Make sure you have ``autoReconnect`` enabled. See `Client`_.
+
+Voice
+------
+
+Often, especially if you're on Windows, voice will not work out of the box.
+Follow the steps below, one by one.
+
+
+- Is your system supported? The following are:
+    - Linux x64 & ia32
+    - Linux ARM (Raspberry Pi 1 & 2)
+    - Mac OS X x64
+    - Windows x64
+- Did you install Python 2.7.x correctly? Is it in your PATH? ``python -V``. If not, install it correctly or try reinstalling.
+    - **Windows** - See https://python.org/downloads/
+    - **Linux / Mac OS** - Unix systems should already have it installed, but if not, use the OS's package manager
+- Did you install FFMPEG correctly? Is it in your PATH? ``ffmpeg -version``. If not, install it correctly or try reinstalling.
+    - **Windows** - `Follow this guide`_
+    - **Linux / Mac OS** - Use your OS's package manager
+- Did you install the required C++ compiler tool for your OS? If not, install the corresponding program, **then** try reinstalling discord.js ``npm i -S discord.js``
+    - **Windows** - `Visual Studio 2015`_ with `C++ Support enabled`_
+    - **Linux** - build-essential
+    - **Mac OS** - Xcode CLI tools
+
+If you're still having problems try
+    - ``npm cache clean``
+    - ``npm config set msvs_version 2015``
+    - ``npm i -S discord.js``
+
+If nothing of the above helped, feel free to jump on the `discord.js channel in the API server`_
+
 .. _discord.js channel in the API server : https://discord.gg/0SBTUU1wZTYcFtmP
-.. _make an issue : https://github.com/hydrabolt/discord.js/issues
+.. _make an issue : https://github.com/hydrabolt/discord.js/issues
+.. _Follow this guide : http://adaptivesamples.com/how-to-install-ffmpeg-on-windows/
+.. _Visual Studio 2015 : https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
+.. _C++ Support enabled : https://social.msdn.microsoft.com/Forums/getfile/740020