From 422fffdbfb4cc177a4d98b5c4a1a473fad52663c Mon Sep 17 00:00:00 2001 From: Brian Tanner Date: Wed, 13 Jul 2016 21:05:54 -0400 Subject: [PATCH] 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 * _ --- docs/docs_cache.rst | 1 + docs/docs_client.rst | 6 +-- docs/docs_invite.rst | 27 ++++++++++++- docs/docs_message.rst | 49 ++++++++++++++++++++++ docs/docs_pmchannel.rst | 64 ++++++++++++++++++++++++++++- docs/docs_role.rst | 34 +++++++++++++++- docs/docs_textchannel.rst | 73 ++++++++++++++++++++++++++++++++- docs/docs_user.rst | 76 ++++++++++++++++++++++++++++++++++- docs/docs_voicechannel.rst | 18 ++++++++- docs/docs_voiceconnection.rst | 5 +++ docs/index.rst | 1 + docs/troubleshooting.rst | 42 ++++++++++++++++++- 12 files changed, 386 insertions(+), 10 deletions(-) diff --git a/docs/docs_cache.rst b/docs/docs_cache.rst index e46095ebd..0a22bc2a0 100644 --- 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. diff --git a/docs/docs_client.rst b/docs/docs_client.rst index a3300555f..ad6d246f1 100755 --- 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 diff --git a/docs/docs_invite.rst b/docs/docs_invite.rst index 14b486a54..236270b85 100644 --- 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. \ No newline at end of file +`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 \ No newline at end of file diff --git a/docs/docs_message.rst b/docs/docs_message.rst index 1a98abd7f..843610191 100644 --- 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 \ No newline at end of file diff --git a/docs/docs_pmchannel.rst b/docs/docs_pmchannel.rst index 08ff8ede7..18a105bb4 100644 --- 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. \ No newline at end of file +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 \ No newline at end of file diff --git a/docs/docs_role.rst b/docs/docs_role.rst index b3b01861e..2c69d6e31 100644 --- 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. \ No newline at end of file +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 \ No newline at end of file diff --git a/docs/docs_textchannel.rst b/docs/docs_textchannel.rst index fc9f3406b..4dd15e6c1 100644 --- 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. \ No newline at end of file +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 \ No newline at end of file diff --git a/docs/docs_user.rst b/docs/docs_user.rst index 71082350e..a214a1c4c 100755 --- 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. \ No newline at end of file +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 \ No newline at end of file diff --git a/docs/docs_voicechannel.rst b/docs/docs_voicechannel.rst index 1d3e32ea6..e94389573 100644 --- 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_ \ No newline at end of file +| **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 \ No newline at end of file diff --git a/docs/docs_voiceconnection.rst b/docs/docs_voiceconnection.rst index 544c58913..327c88205 100644 --- 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 ~~~~~~~~~~ diff --git a/docs/index.rst b/docs/index.rst index 40c8516c6..99d1c5324 100644 --- 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 diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 6542d5822..6984c1b3e 100644 --- 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 \ No newline at end of file +.. _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