From 52d536fe6aa74f07224f0daa2f7d5858fce33223 Mon Sep 17 00:00:00 2001 From: Christopher F Date: Thu, 25 Aug 2016 19:06:26 -0400 Subject: [PATCH] Include Documentation for Migrating from 0.9.x to 1.0 --- docs/api/.gitignore | 1 + docs/docfx.json | 3 + docs/guides/samples/migrating/event.cs | 4 + docs/guides/samples/migrating/sync_event.cs | 5 ++ docs/guides/terminology.md | 5 ++ docs/migrating.md | 81 +++++++++++++++++++++ docs/toc.yml | 2 + 7 files changed, 101 insertions(+) create mode 100644 docs/guides/samples/migrating/event.cs create mode 100644 docs/guides/samples/migrating/sync_event.cs create mode 100644 docs/migrating.md diff --git a/docs/api/.gitignore b/docs/api/.gitignore index b37a96f6e..bffdb3075 100644 --- a/docs/api/.gitignore +++ b/docs/api/.gitignore @@ -3,3 +3,4 @@ # temp file # ############### *.yml +.manifest \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json index cd60352b4..e0b5514cd 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -65,6 +65,9 @@ "template": [ "default" ], + "globalMetadata": { + "_appFooter": "Discord.Net (c) 2015-2016" + }, "noLangKeyword": false } } \ No newline at end of file diff --git a/docs/guides/samples/migrating/event.cs b/docs/guides/samples/migrating/event.cs new file mode 100644 index 000000000..8719942f2 --- /dev/null +++ b/docs/guides/samples/migrating/event.cs @@ -0,0 +1,4 @@ +_client.MessageReceived += async (msg) => +{ + await msg.Channel.SendMessageAsync(msg.Content); +} \ No newline at end of file diff --git a/docs/guides/samples/migrating/sync_event.cs b/docs/guides/samples/migrating/sync_event.cs new file mode 100644 index 000000000..f4a55cdd3 --- /dev/null +++ b/docs/guides/samples/migrating/sync_event.cs @@ -0,0 +1,5 @@ +_client.Log += (msg) => +{ + Console.WriteLine(msg.ToString()); + return Task.CompletedTask; +} \ No newline at end of file diff --git a/docs/guides/terminology.md b/docs/guides/terminology.md index fa52fb17c..2633a56c6 100644 --- a/docs/guides/terminology.md +++ b/docs/guides/terminology.md @@ -1,3 +1,8 @@ +--- +uid: Terminology +title: Terminology +--- + # Terminology ## Preface diff --git a/docs/migrating.md b/docs/migrating.md new file mode 100644 index 000000000..5abceb46c --- /dev/null +++ b/docs/migrating.md @@ -0,0 +1,81 @@ +# Migrating from 0.9 + +**1.0.0 is the biggest breaking change the library has gone through, do to massive +changes in the design of the library.** + +>A medium to advanced understanding is recommended when working with this library. + +One of the biggest major changes from `0.9.x` is the exclusive use of interfaces. +For the most part, your usability will be very similar to the 0.9 approach of concrete +classes. You **will** be required to cast some entities; this is outlined in a later +section. + +It is recommended to familiarize yourself with the entities in 1.0 before continuing. +Feel free to look through the library's source directly, look through IntelliSense, or +look through our hosted [API Documentation](xref:Discord). + +## Entities + +Most API models function _similarly_ to 0.9, however their names have been changed. +You should also keep in mind that we now separate different types of Channels and Users. + +Take a look at inheritance section of @Terminology for an example of how inheritance and interfaces +work in 1.0 + +Below is a table that compares most common 0.9 entities to their 1.0 counterparts. + +>This should be used mostly for migration purposes. Please take some time to consider whether +>or not you are using the right "tool for the job" when working with 1.0 + +| 0.9 | 1.0 | Notice | +| --- | --- | ------ | +| Server | @Discord.IGuild | +| Channel | @Discord.IGuildChannel | Applies only to channels that are members of a Guild | +| Channel.IsPrivate | @Discord.IDMChannel +| ChannelType.Text | @Discord.ITextChannel | This applies only to Text Channels in Guilds +| ChannelType.Voice | @Discord.IVoiceChannel | This applies only to Voice Channels in Guilds +| User | @Discord.IGuildUser | This applies only to users belonging to a Guild* +| Profile | @Discord.ISelfUser +| Message | @Discord.IMessage + +\* To retrieve an @Discord.IGuildUser, you must retrieve the user from an @Discord.IGuild. +[IDiscordClient.GetUserAsync](xref:Discord.IDiscordClient#Discord_IDiscordClient_GetUserAsync_System_UInt64_) +returns a @Discord.IUser, which only contains the information that Discord exposes for public users. + +## Event Registration + +Prior to 1.0, events were registered using the standard c# `Handler(EventArgs)` pattern. In 1.0, +events are delegates, but are still registered the same. + +For example, let's look at [DiscordSocketClient.MessageReceived](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_MessageReceived) + +To hook an event into MessageReceived, we now use the following code: +[!code-csharp[Event Registration](guides/samples/migrating/event.cs)] + +> **All Event Handlers in 1.0 MUST return Task!** + +If your event handler is marked as `async`, it will automatically return `Task`. However, +if you do not need to execute asynchronus code, do _not_ mark your handler as `async`, and instead, +stick a `return Task.CompletedTask` at the bottom. + +[!code-csharp[Sync Event Registration](guides/samples/migrating/sync_event.cs)] + +**Event handlers no longer require a sender.** The only arguments your event handler needs to accept +are the parameters used by the event. It is recommended to look at the event in IntelliSense or on the +API docs before implementing it. + +## Async + +Nearly everything in 1.0 is an async Task. You should always await any tasks you invoke. + +However, when using WebSockets, you may find this both inconvienent, and unnecessary, as many of the +WebSocket implementations of the interfaces keep their own local cache of objects, rendering the use +of async redundant. + +**As of right now,** there are extension methods you can use, located in `Discord.WebSocket` that will +provide java-esque, synchronus `GetXXX` methods to replace the asynchronus methods on WebSocket entities. + +This functionality may be changed at a later date, we are currently reviewing this implementation and +alternative methods. + +For your reference, you may want to look through the extension classes located in @Discord.WebSocket \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml index c08e708bf..47a8a22c1 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,6 +1,8 @@ - name: Guides href: guides/ +- name: Migrating + href: migrating.md - name: API Documentation href: api/ homepage: api/index.md