Browse Source

Updated Code Samples for compatibility with 0.9; fixed events; fixed rST

tags/docs-0.9
Christopher F 9 years ago
parent
commit
9b2be11638
14 changed files with 57 additions and 46 deletions
  1. +1
    -1
      docs/features/commands.rst
  2. +9
    -11
      docs/features/events.rst
  3. +11
    -5
      docs/features/logging.rst
  4. +5
    -2
      docs/features/permissions.rst
  5. +1
    -1
      docs/features/server-management.rst
  6. +2
    -2
      docs/features/user-management.rst
  7. +1
    -1
      docs/features/voice.rst
  8. +3
    -3
      docs/getting_started.rst
  9. +2
    -1
      docs/global.txt
  10. +5
    -5
      docs/index.rst
  11. +7
    -7
      docs/samples/events.cs
  12. +6
    -3
      docs/samples/getting_started.cs
  13. +2
    -3
      docs/samples/logging.cs
  14. +2
    -1
      docs/samples/permissions.cs

+ 1
- 1
docs/features/commands.rst View File

@@ -1,7 +1,7 @@
|stub| Commands
===============

The `Discord.Net.Commands`_ package DiscordBotClient extends DiscordClient with support for commands.
The `Discord.Net.Commands`_ package extends DiscordClient with a built-in Commands Handler.

.. _Discord.Net.Commands: https://www.nuget.org/packages/Discord.Net.Commands



+ 9
- 11
docs/features/events.rst View File

@@ -3,21 +3,19 @@ Events

Usage
-----
Messages from the Discord server are exposed via events on the DiscordClient class and follow the standard EventHandler<EventArgs> C# pattern.
Messages from the Discord server are exposed via events on the DiscordClient class and follow the standard EventHandler<EventArgs> C# pattern.

.. warning::
Note that all synchronous code in an event handler will run on the gateway socket's thread and should be handled as quickly as possible.
Note that all synchronous code in an event handler will run on the gateway socket's thread and should be handled as quickly as possible.
Using the async-await pattern to let the thread continue immediately is recommended and is demonstrated in the examples below.

Connection State
----------------
Ready
-----

Connection Events will be raised when the Connection State of your client changes.
The Ready Event is raised only once, when your client finishes processing the READY packet from Discord.

This has replaced the previous "Connected" event, and indicates that it is safe to begin retrieving users, channels, or servers from the cache.

.. warning::
You should not use DiscordClient.Connected to run code when your client first connects to Discord.
If you lose connection and automatically reconnect, this code will be ran again, which may lead to unexpected behavior.
Messages
--------

@@ -26,7 +24,7 @@ Messages

Example of MessageReceived:

.. code-block:: c#
.. code-block:: csharp6

// (Preface: Echo Bots are discouraged, make sure your bot is not running in a public server if you use them)

@@ -56,7 +54,7 @@ There are several user events:

Examples:

.. code-block:: c#
.. code-block:: csharp6

// Register a Hook into the UserBanned event using a Lambda
_client.UserBanned += async (s, e) => {


+ 11
- 5
docs/features/logging.rst View File

@@ -2,12 +2,12 @@ Logging
=======

Discord.Net will log all of its events/exceptions using a built-in LogManager.
This LogManager can be accessed through DiscordClient.Log
This LogManager can be accessed through ``DiscordClient.Log``

Usage
-----

To handle Log Messages through Discord.Net's Logger, you must hook into the Log.Message<LogMessageEventArgs> Event.
To handle Log Messages through Discord.Net's Logger, you must hook into the ``Log.Message<LogMessageEventArgs>`` Event.

The LogManager does not provide a string-based result for the message, you must put your own message format together using the data provided through LogMessageEventArgs
See the Example for a snippet of logging.
@@ -17,19 +17,25 @@ Logging Your Own Data

The LogManager included in Discord.Net can also be used to log your own messages.

You can use DiscordClient.Log.Log(LogSeverity, Source, Message, Exception), or one of the shortcut helpers, to log data.
You can use ``DiscordClient.Log.Log(LogSeverity, Source, Message, [Exception])``, or one of the shortcut helpers, to log data.

Example:
.. code-block:: c#

.. code-block:: csharp6

_client.MessageReceived += async (s, e) {
// Log a new Message with Severity Info, Sourced from 'MessageReceived', with the Message Contents.
_client.Log.Info("MessageReceived", e.Message.Text, null);
};


.. warning::

Starting in Discord.Net 1.0, you will not be able to log your own messages. You will need to create your own Logging manager, or use a pre-existing one.

Example
-------

.. literalinclude:: /samples/logging.cs
:language: c#
:language: csharp6
:tab-width: 2

+ 5
- 2
docs/features/permissions.rst View File

@@ -1,5 +1,7 @@
Permissions
===========
|stub| Permissions
==================

|outdated|

There are two types of permissions: *Channel Permissions* and *Server Permissions*.

@@ -61,6 +63,7 @@ KickMembers Server Kick users from the server. They can still rejoi
ManageRoles Server Manage roles on the server, and their permissions.
ManageChannels Server Manage channels that exist on the server (add, remove them)
ManageServer Server Manage the server settings.
======================= ======= ==============

Roles
-----


+ 1
- 1
docs/features/server-management.rst View File

@@ -10,7 +10,7 @@ You can create Channels, Invites, and Roles on a server using the CreateChannel,

You may also edit a server's name, icon, and region.

.. code-block:: c#
.. code-block:: csharp6

// Create a Channel and retrieve the Channel object
var _channel = await _server.CreateChannel("announcements", ChannelType.Text);


+ 2
- 2
docs/features/user-management.rst View File

@@ -6,7 +6,7 @@ Banning

To ban a user, invoke the Ban function on a Server object.

.. code-block:: c#
.. code-block:: csharp6

_server.Ban(_user, 30);

@@ -17,6 +17,6 @@ Kicking

To kick a user, invoke the Kick function on the User.

.. code-block:: c#
.. code-block:: csharp6

_user.Kick();

+ 1
- 1
docs/features/voice.rst View File

@@ -10,4 +10,4 @@ Multi-Server Broadcasting
-------------------------

Receiving
---------
---------

+ 3
- 3
docs/getting_started.rst View File

@@ -22,12 +22,12 @@ You can get Discord.Net from NuGet:

If you have trouble installing from NuGet, try installing dependencies manually.

You can also pull the latest source from `GitHub`_
You can also pull the latest source from `GitHub`_

.. _Discord.Net: https://www.nuget.org/packages/Discord.Net
.. _Discord.Net.Commands: https://www.nuget.org/packages/Discord.Net.Commands
.. _Discord.Net.Modules: https://www.nuget.org/packages/Discord.Net.Modules
.. _Discord.Net.Modules: https://www.nuget.org/packages/Discord.Net.Audio
.. _Discord.Net.Audio: https://www.nuget.org/packages/Discord.Net.Audio
.. _GitHub: https://github.com/RogueException/Discord.Net/

Async
@@ -42,7 +42,7 @@ For more information, go to `MSDN's Await-Async section`_.

Example
-------
.. literalinclude:: samples/getting_started.cs
:language: csharp6
:tab-width: 2

+ 2
- 1
docs/global.txt View File

@@ -1,2 +1,3 @@
.. |stub| unicode:: U+1F527
.. |stub-desc| replace:: This page is a placeholder and has not been written yet. It should be coming soon!
.. |stub-desc| replace:: This page is a placeholder and has not been written yet. It should be coming soon!
.. |outdated| replace:: **This page is currently out-of-date. The information below may be inaccurate.**

+ 5
- 5
docs/index.rst View File

@@ -9,13 +9,13 @@ Feel free to join us in the `Discord API chat`_.
.. _Discord chat service: https://discordapp.com
.. _Discord API chat: https://discord.gg/0SBTUU1wZTVjAMPx

.. warn::
.. warning::

This is a beta!
This is a beta!

This library has been built thanks to a community effort reverse engineering the Discord client.
As the API is still unofficial, it may change at any time without notice, breaking this library as well.
Discord.Net itself is still in development (and is currently undergoing a rewrite) and you may encounter breaking changes throughout development until the official Discord API is released.
This library has been built thanks to a community effort reverse engineering the Discord client.
As the API is still unofficial, it may change at any time without notice, breaking this library as well.
Discord.Net itself is still in development (and is currently undergoing a rewrite) and you may encounter breaking changes throughout development until the official Discord API is released.

It is highly recommended that you always use the latest version and please report any bugs you find to our `Discord chat`_.



+ 7
- 7
docs/samples/events.cs View File

@@ -1,20 +1,20 @@
class Program
{
private static DiscordBotClient _client;
private static DiscordClient _client;
static void Main(string[] args)
{
var client = new DiscordClient();
_client = new DiscordClient();

// Handle Events using Lambdas
client.MessageCreated += (s, e) =>
_client.MessageReceived += (s, e) =>
{
if (!e.Message.IsAuthor)
await client.SendMessage(e.Message.ChannelId, "foo");
await e.Channel.SendMessage("foo");
}

// Handle Events using Event Handlers
EventHandler<MessageEventArgs> handler = new EventHandler<MessageEventArgs>(HandleMessageCreated);
client.MessageCreated += handler;
client.MessageReceived += handler;
}


@@ -22,6 +22,6 @@ class Program
static void HandleMessageCreated(object sender, EventArgs e)
{
if (!e.Message.IsAuthor)
await client.SendMessage(e.Message.ChannelId, "foo");
await e.Channel.SendMessage("bar");
}
}
}

+ 6
- 3
docs/samples/getting_started.cs View File

@@ -2,10 +2,13 @@ class Program
{
static void Main(string[] args)
{
var client = new DiscordClient();
var client = new DiscordClient(x =>
{
LogLevel = LogSeverity.Info
});

//Display all log messages in the console
client.LogMessage += (s, e) => Console.WriteLine($"[{e.Severity}] {e.Source}: {e.Message}");
client.Log.Message += (s, e) => Console.WriteLine($"[{e.Severity}] {e.Source}: {e.Message}");

//Echo back any message received, provided it didn't come from the bot itself
client.MessageReceived += async (s, e) =>
@@ -22,7 +25,7 @@ class Program

//If we are not a member of any server, use our invite code (made beforehand in the official Discord Client)
if (!client.Servers.Any())
await client.AcceptInvite(client.GetInvite("aaabbbcccdddeee"));
await (client.GetInvite("aaabbbcccdddeee")).Accept();
});
}
}

+ 2
- 3
docs/samples/logging.cs View File

@@ -1,6 +1,5 @@
class Program
{
private static DiscordBotClient _client;
static void Main(string[] args)
{
var client = new DiscordClient(x =>
@@ -8,13 +7,13 @@ class Program
LogLevel = LogSeverity.Info
});

_client.Log.Message += (s, e) => Console.WriteLine($"[{e.Severity}] {e.Source}: {e.Message}");
client.Log.Message += (s, e) => Console.WriteLine($"[{e.Severity}] {e.Source}: {e.Message}");

client.ExecuteAndWait(async () =>
{
await client.Connect("discordtest@email.com", "Password123");
if (!client.Servers.Any())
await client.AcceptInvite("aaabbbcccdddeee");
await (client.GetInvite("aaabbbcccdddeee")).Accept();
});
}
}

+ 2
- 1
docs/samples/permissions.cs View File

@@ -1,3 +1,5 @@
/* --- OUTDATED --- */

// Find a User's Channel Permissions
var userChannelPermissions = user.GetPermissions(channel);

@@ -11,4 +13,3 @@ var userPerms = user.GetPermissions(channel);
userPerms.ReadMessageHistory = false;
userPerms.AttachFiles = null;
channel.AddPermissionsRule(user, userPerms);
}

Loading…
Cancel
Save