diff --git a/src/Discord.Net/Audio/AudioMode.cs b/src/Discord.Net/Audio/AudioMode.cs index 7cc5a08c1..bc883d6c9 100644 --- a/src/Discord.Net/Audio/AudioMode.cs +++ b/src/Discord.Net/Audio/AudioMode.cs @@ -2,12 +2,17 @@ namespace Discord.Audio { + /// Specifies an audio mode for Discord. [Flags] public enum AudioMode : byte { + /// Audio send/receive is disabled. Disabled = 0, + /// Audio can only be broadcasted by the client. Outgoing = 1, + /// Audio can only be received by the client. Incoming = 2, + /// Audio can be sent and received by the client. Both = Outgoing | Incoming } } diff --git a/src/Discord.Net/Audio/IAudioClient.cs b/src/Discord.Net/Audio/IAudioClient.cs index 312152142..546b9e3f7 100644 --- a/src/Discord.Net/Audio/IAudioClient.cs +++ b/src/Discord.Net/Audio/IAudioClient.cs @@ -5,19 +5,26 @@ namespace Discord.Audio { public interface IAudioClient { + /// Fired when the client connects to Discord. event Func Connected; + /// Fired when the client disconnects from Discord. event Func Disconnected; + /// Fired in response to a heartbeat, providing the old and new latency. event Func LatencyUpdated; + /// Gets the API client used for communicating with Discord. DiscordVoiceAPIClient ApiClient { get; } /// Gets the current connection state of this client. ConnectionState ConnectionState { get; } /// Gets the estimated round-trip latency, in milliseconds, to the gateway server. int Latency { get; } + /// Disconnects the current client from Discord. Task DisconnectAsync(); + /// Creates an Opus stream for sending raw Opus-encoded data. RTPWriteStream CreateOpusStream(int samplesPerFrame, int bufferSize = 4000); + /// Creates a PCM stream for sending unencoded PCM data. OpusEncodeStream CreatePCMStream(int samplesPerFrame, int? bitrate = null, OpusApplication application = OpusApplication.MusicOrMixed, int bufferSize = 4000); } } diff --git a/src/Discord.Net/Audio/Opus/OpusApplication.cs b/src/Discord.Net/Audio/Opus/OpusApplication.cs index d6a3ce0cf..12a6ff822 100644 --- a/src/Discord.Net/Audio/Opus/OpusApplication.cs +++ b/src/Discord.Net/Audio/Opus/OpusApplication.cs @@ -1,9 +1,16 @@ namespace Discord.Audio { + /// The types of encoding which Opus supports during encoding. public enum OpusApplication : int { + /// Specifies that the uses + /// encoding to improve the quality of voice communication. Voice = 2048, + /// Specifies that the uses + /// encoding to improve the overall quality of mixed-media audio transmission. MusicOrMixed = 2049, + /// Specifies that the uses + /// encoding to reduce overall latency. LowLatency = 2051 } } diff --git a/src/Discord.Net/Audio/Opus/OpusDecoder.cs b/src/Discord.Net/Audio/Opus/OpusDecoder.cs index ea9376f82..99e0152bc 100644 --- a/src/Discord.Net/Audio/Opus/OpusDecoder.cs +++ b/src/Discord.Net/Audio/Opus/OpusDecoder.cs @@ -24,7 +24,9 @@ namespace Discord.Audio /// Produces PCM samples from Opus-encoded audio. /// PCM samples to decode. /// Offset of the frame in input. + /// Number of bytes of the frame in input. /// Buffer to store the decoded frame. + /// Zero-based offset for the output. public unsafe int DecodeFrame(byte[] input, int inputOffset, int inputCount, byte[] output, int outputOffset) { int result = 0; diff --git a/src/Discord.Net/Audio/Opus/OpusEncoder.cs b/src/Discord.Net/Audio/Opus/OpusEncoder.cs index c1eb3843d..5ed34ac3d 100644 --- a/src/Discord.Net/Audio/Opus/OpusEncoder.cs +++ b/src/Discord.Net/Audio/Opus/OpusEncoder.cs @@ -31,6 +31,9 @@ namespace Discord.Audio /// Produces Opus encoded audio from PCM samples. /// PCM samples to encode. /// Buffer to store the encoded frame. + /// Offset of the frame in input. + /// Number of bytes of the frame in input. + /// Zero-based offset for the output. /// Length of the frame contained in outputBuffer. public unsafe int EncodeFrame(byte[] input, int inputOffset, int inputCount, byte[] output, int outputOffset) { diff --git a/src/Discord.Net/Audio/Sodium/SecretBox.cs b/src/Discord.Net/Audio/Sodium/SecretBox.cs index 4187c9f08..4e601fb25 100644 --- a/src/Discord.Net/Audio/Sodium/SecretBox.cs +++ b/src/Discord.Net/Audio/Sodium/SecretBox.cs @@ -3,13 +3,14 @@ using System.Runtime.InteropServices; namespace Discord.Audio { - public unsafe static class SecretBox + public unsafe static class SecretBox // TODO: should this be public? { [DllImport("libsodium", EntryPoint = "crypto_secretbox_easy", CallingConvention = CallingConvention.Cdecl)] private static extern int SecretBoxEasy(byte* output, byte* input, long inputLength, byte[] nonce, byte[] secret); [DllImport("libsodium", EntryPoint = "crypto_secretbox_open_easy", CallingConvention = CallingConvention.Cdecl)] private static extern int SecretBoxOpenEasy(byte* output, byte* input, long inputLength, byte[] nonce, byte[] secret); + /// Encrypts a payload with the given nonce and secret. public static int Encrypt(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset, byte[] nonce, byte[] secret) { fixed (byte* inPtr = input) @@ -21,6 +22,7 @@ namespace Discord.Audio return inputLength + 16; } } + /// Decrypts a payload with the given nonce and secret. public static int Decrypt(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset, byte[] nonce, byte[] secret) { fixed (byte* inPtr = input) diff --git a/src/Discord.Net/Audio/Streams/OpusDecodeStream.cs b/src/Discord.Net/Audio/Streams/OpusDecodeStream.cs index c059955a8..1c7cfe765 100644 --- a/src/Discord.Net/Audio/Streams/OpusDecodeStream.cs +++ b/src/Discord.Net/Audio/Streams/OpusDecodeStream.cs @@ -1,5 +1,6 @@ namespace Discord.Audio { + /// A stream which decodes Opus frames as they are read. public class OpusDecodeStream : RTPReadStream { private readonly byte[] _buffer; @@ -13,12 +14,14 @@ _decoder = new OpusDecoder(samplingRate, channels); } + /// Reads Opus-encoded frame from the stream, filling the buffer with PCM data public override int Read(byte[] buffer, int offset, int count) { count = _decoder.DecodeFrame(buffer, offset, count, _buffer, 0); return base.Read(_buffer, 0, count); } + /// protected override void Dispose(bool disposing) { base.Dispose(disposing); diff --git a/src/Discord.Net/Audio/Streams/OpusEncodeStream.cs b/src/Discord.Net/Audio/Streams/OpusEncodeStream.cs index ef773ca56..55d1566d2 100644 --- a/src/Discord.Net/Audio/Streams/OpusEncodeStream.cs +++ b/src/Discord.Net/Audio/Streams/OpusEncodeStream.cs @@ -1,8 +1,11 @@ namespace Discord.Audio { + /// A stream which encodes Opus frames as raw PCM data is written. public class OpusEncodeStream : RTPWriteStream { - public int SampleRate = 48000; + /// The sample rate of the Opus stream. + public int SampleRate = 48000; // TODO: shouldn't these be readonly? + /// The number of channels of the Opus stream. public int Channels = 2; private readonly OpusEncoder _encoder; @@ -18,12 +21,14 @@ _encoder.SetBitrate(bitrate.Value); } + /// Writes Opus-encoded PCM data to the stream. public override void Write(byte[] buffer, int offset, int count) { count = _encoder.EncodeFrame(buffer, offset, count, _buffer, 0); base.Write(_buffer, 0, count); } + /// protected override void Dispose(bool disposing) { base.Dispose(disposing); diff --git a/src/Discord.Net/Audio/Streams/RTPReadStream.cs b/src/Discord.Net/Audio/Streams/RTPReadStream.cs index 4bf7f5e1b..75dd26e7e 100644 --- a/src/Discord.Net/Audio/Streams/RTPReadStream.cs +++ b/src/Discord.Net/Audio/Streams/RTPReadStream.cs @@ -4,14 +4,18 @@ using System.IO; namespace Discord.Audio { + /// A stream used for reading raw audio data from Discord. public class RTPReadStream : Stream { private readonly BlockingCollection _queuedData; //TODO: Replace with max-length ring buffer private readonly AudioClient _audioClient; private readonly byte[] _buffer, _nonce, _secretKey; + /// public override bool CanRead => true; + /// public override bool CanSeek => false; + /// public override bool CanWrite => true; internal RTPReadStream(AudioClient audioClient, byte[] secretKey, int bufferSize = 4000) @@ -23,12 +27,14 @@ namespace Discord.Audio _nonce = new byte[24]; } + /// public override int Read(byte[] buffer, int offset, int count) { var queuedData = _queuedData.Take(); Buffer.BlockCopy(queuedData, 0, buffer, offset, Math.Min(queuedData.Length, count)); return queuedData.Length; } + /// public override void Write(byte[] buffer, int offset, int count) { Buffer.BlockCopy(buffer, 0, _nonce, 0, 12); @@ -38,16 +44,21 @@ namespace Discord.Audio _queuedData.Add(newBuffer); } + /// public override void Flush() { throw new NotSupportedException(); } + /// public override long Length { get { throw new NotSupportedException(); } } + /// public override long Position { get { throw new NotSupportedException(); } set { throw new NotSupportedException(); } } + /// public override void SetLength(long value) { throw new NotSupportedException(); } + /// public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(); } } } diff --git a/src/Discord.Net/Audio/Streams/RTPWriteStream.cs b/src/Discord.Net/Audio/Streams/RTPWriteStream.cs index d547f021a..427b65299 100644 --- a/src/Discord.Net/Audio/Streams/RTPWriteStream.cs +++ b/src/Discord.Net/Audio/Streams/RTPWriteStream.cs @@ -3,6 +3,7 @@ using System.IO; namespace Discord.Audio { + /// A stream used for writing raw audio data to Discord. public class RTPWriteStream : Stream { private readonly AudioClient _audioClient; @@ -10,10 +11,14 @@ namespace Discord.Audio private int _samplesPerFrame; private uint _ssrc, _timestamp = 0; + /// The current output buffer. protected readonly byte[] _buffer; + /// public override bool CanRead => false; + /// public override bool CanSeek => false; + /// public override bool CanWrite => true; internal RTPWriteStream(AudioClient audioClient, byte[] secretKey, int samplesPerFrame, uint ssrc, int bufferSize = 4000) @@ -32,6 +37,7 @@ namespace Discord.Audio _nonce[11] = (byte)(_ssrc >> 0); } + /// public override void Write(byte[] buffer, int offset, int count) { unchecked @@ -51,17 +57,23 @@ namespace Discord.Audio _audioClient.Send(_buffer, count + 12); } + /// public override void Flush() { } + /// public override long Length { get { throw new NotSupportedException(); } } + /// public override long Position { get { throw new NotSupportedException(); } set { throw new NotSupportedException(); } } + /// public override int Read(byte[] buffer, int offset, int count) { throw new NotSupportedException(); } + /// public override void SetLength(long value) { throw new NotSupportedException(); } + /// public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(); } } } diff --git a/src/Discord.Net/ConnectionState.cs b/src/Discord.Net/ConnectionState.cs index 42c505ccd..e4658b884 100644 --- a/src/Discord.Net/ConnectionState.cs +++ b/src/Discord.Net/ConnectionState.cs @@ -1,10 +1,15 @@ namespace Discord { + /// Connection state for clients public enum ConnectionState : byte { + /// Not connected to Discord Disconnected, + /// Currently connecting to Discord Connecting, + /// Connected to Discord Connected, + /// Disconnecting from Discord Disconnecting } } diff --git a/src/Discord.Net/DiscordConfig.cs b/src/Discord.Net/DiscordConfig.cs index 737cf0050..9fcb26e36 100644 --- a/src/Discord.Net/DiscordConfig.cs +++ b/src/Discord.Net/DiscordConfig.cs @@ -2,20 +2,29 @@ namespace Discord { + /// Stores common configuration settings public class DiscordConfig { - public const int APIVersion = 6; + /// The version of Discord's REST API which is used + public const int APIVersion = 6; + /// Version information about Discord.Net public static string Version { get; } = typeof(DiscordConfig).GetTypeInfo().Assembly.GetCustomAttribute()?.InformationalVersion ?? typeof(DiscordConfig).GetTypeInfo().Assembly.GetName().Version.ToString(3) ?? "Unknown"; + /// The base URL for all REST API requests public static readonly string ClientAPIUrl = $"https://discordapp.com/api/v{APIVersion}/"; + /// The base URL for all CDN requests public const string CDNUrl = "https://discordcdn.com/"; + /// The base URL for all invite links public const string InviteUrl = "https://discord.gg/"; + /// The maximum amount of characters which can be sent in a message public const int MaxMessageSize = 2000; + /// The maximum number of messages which can be received in a batch public const int MaxMessagesPerBatch = 100; + /// The maximum number of users which can be received in a batch public const int MaxUsersPerBatch = 1000; /// Gets or sets the minimum log level severity that will be sent to the LogMessage event. diff --git a/src/Discord.Net/Entities/Channels/ChannelType.cs b/src/Discord.Net/Entities/Channels/ChannelType.cs index f05f1598e..378ad3e6a 100644 --- a/src/Discord.Net/Entities/Channels/ChannelType.cs +++ b/src/Discord.Net/Entities/Channels/ChannelType.cs @@ -1,10 +1,15 @@ namespace Discord { + /// Specifies the type of channel a message was sent to or eceived from. public enum ChannelType { + /// A text channel Text = 0, + /// A direct-message text channel DM = 1, + /// A voice channel Voice = 2, + /// A group channel Group = 3 } } diff --git a/src/Discord.Net/Format.cs b/src/Discord.Net/Format.cs index d31f0ad0a..33ad5f6f8 100644 --- a/src/Discord.Net/Format.cs +++ b/src/Discord.Net/Format.cs @@ -1,5 +1,6 @@ namespace Discord { + /// Contains common macros for formatting text using Markdown public static class Format { // Characters which need escaping diff --git a/src/Discord.Net/LogSeverity.cs b/src/Discord.Net/LogSeverity.cs index 785b0ef46..e563abf77 100644 --- a/src/Discord.Net/LogSeverity.cs +++ b/src/Discord.Net/LogSeverity.cs @@ -1,12 +1,19 @@ namespace Discord { + /// The severity of a log message public enum LogSeverity { + /// Used when a critical, non-recoverable error occurs Critical = 0, + /// Used when a recoverable error occurs Error = 1, + /// Used when a warning occurs Warning = 2, + /// Used for general, informative messages Info = 3, + /// Used for debugging purposes Verbose = 4, + /// Used for debugging purposes Debug = 5 } } diff --git a/src/Discord.Net/LoginState.cs b/src/Discord.Net/LoginState.cs index 42b6ecac9..d10eaf74c 100644 --- a/src/Discord.Net/LoginState.cs +++ b/src/Discord.Net/LoginState.cs @@ -1,10 +1,15 @@ namespace Discord { + /// Login state for clients public enum LoginState : byte { + /// Logged out LoggedOut, + /// Logging in LoggingIn, + /// Logged in LoggedIn, + /// Logging out LoggingOut } } diff --git a/src/Discord.Net/Net/Rest/DefaultRestClient.cs b/src/Discord.Net/Net/Rest/DefaultRestClient.cs index bcad2ece4..4f0d8b436 100644 --- a/src/Discord.Net/Net/Rest/DefaultRestClient.cs +++ b/src/Discord.Net/Net/Rest/DefaultRestClient.cs @@ -13,6 +13,7 @@ using System.Threading.Tasks; namespace Discord.Net.Rest { + /// A default implementation of a public sealed class DefaultRestClient : IRestClient { private const int HR_SECURECHANNELFAILED = -2146233079; @@ -24,6 +25,7 @@ namespace Discord.Net.Rest private CancellationToken _cancelToken, _parentToken; private bool _isDisposed; + /// Creates a new instance of public DefaultRestClient(string baseUrl) { _baseUrl = baseUrl; @@ -50,29 +52,34 @@ namespace Discord.Net.Rest _isDisposed = true; } } + /// Disposes any resources allocated by this instance. public void Dispose() { Dispose(true); } + /// public void SetHeader(string key, string value) { _client.DefaultRequestHeaders.Remove(key); if (value != null) _client.DefaultRequestHeaders.Add(key, value); } + /// public void SetCancelToken(CancellationToken cancelToken) { _parentToken = cancelToken; _cancelToken = CancellationTokenSource.CreateLinkedTokenSource(_parentToken, _cancelTokenSource.Token).Token; } + /// public async Task SendAsync(string method, string endpoint, bool headerOnly = false) { string uri = Path.Combine(_baseUrl, endpoint); using (var restRequest = new HttpRequestMessage(GetMethod(method), uri)) return await SendInternalAsync(restRequest, headerOnly).ConfigureAwait(false); } + /// public async Task SendAsync(string method, string endpoint, string json, bool headerOnly = false) { string uri = Path.Combine(_baseUrl, endpoint); @@ -82,6 +89,7 @@ namespace Discord.Net.Rest return await SendInternalAsync(restRequest, headerOnly).ConfigureAwait(false); } } + /// public async Task SendAsync(string method, string endpoint, IReadOnlyDictionary multipartParams, bool headerOnly = false) { string uri = Path.Combine(_baseUrl, endpoint); diff --git a/src/Discord.Net/Net/Rest/IRestClient.cs b/src/Discord.Net/Net/Rest/IRestClient.cs index 57b5f91ca..51a2a33d5 100644 --- a/src/Discord.Net/Net/Rest/IRestClient.cs +++ b/src/Discord.Net/Net/Rest/IRestClient.cs @@ -8,11 +8,16 @@ namespace Discord.Net.Rest //TODO: Add docstrings public interface IRestClient { + /// Sets a header to be used in REST requests. void SetHeader(string key, string value); + /// Sets the global cancellation token for any requests made by this instance. void SetCancelToken(CancellationToken cancelToken); + /// Sends a request with no body to the given endpoint. Task SendAsync(string method, string endpoint, bool headerOnly = false); + /// Sends a request with a body to the given endpoint. Task SendAsync(string method, string endpoint, string json, bool headerOnly = false); + /// Sends a multipart request with the given parameters to the given endpoint. Task SendAsync(string method, string endpoint, IReadOnlyDictionary multipartParams, bool headerOnly = false); } } diff --git a/src/Discord.Net/Net/Rest/RestClientProvider.cs b/src/Discord.Net/Net/Rest/RestClientProvider.cs index 51a7eb619..8377a5255 100644 --- a/src/Discord.Net/Net/Rest/RestClientProvider.cs +++ b/src/Discord.Net/Net/Rest/RestClientProvider.cs @@ -1,4 +1,5 @@ namespace Discord.Net.Rest { + /// A delegate for creating a user-defined implementation of public delegate IRestClient RestClientProvider(string baseUrl); } diff --git a/src/Discord.Net/Net/RpcException.cs b/src/Discord.Net/Net/RpcException.cs index 195fad73f..d6cfdebad 100644 --- a/src/Discord.Net/Net/RpcException.cs +++ b/src/Discord.Net/Net/RpcException.cs @@ -2,11 +2,15 @@ namespace Discord { + /// An exception thrown whenever an RPC error occurs. public class RpcException : Exception { + /// The code for this error. public int ErrorCode { get; } + /// The reason this error occured. public string Reason { get; } + /// Creates a new instance of public RpcException(int errorCode, string reason = null) : base($"The server sent error {errorCode}{(reason != null ? $": \"{reason}\"" : "")}") { diff --git a/src/Discord.Net/RequestOptions.cs b/src/Discord.Net/RequestOptions.cs index 242642d56..332b3147b 100644 --- a/src/Discord.Net/RequestOptions.cs +++ b/src/Discord.Net/RequestOptions.cs @@ -1,12 +1,15 @@ namespace Discord { + /// Contains options specific to requests public class RequestOptions { + /// Returns the default options for a request. public static RequestOptions Default => new RequestOptions(); /// The max time, in milliseconds, to wait for this request to complete. If null, a request will not time out. If a rate limit has been triggered for this request's bucket and will not be unpaused in time, this request will fail immediately. public int? Timeout { get; set; } + /// Creates a new instance of the RequestOptions class public RequestOptions() { Timeout = 30000; diff --git a/src/Discord.Net/Rest/DiscordRestClient.cs b/src/Discord.Net/Rest/DiscordRestClient.cs index 11cf10747..e08b8f72c 100644 --- a/src/Discord.Net/Rest/DiscordRestClient.cs +++ b/src/Discord.Net/Rest/DiscordRestClient.cs @@ -15,15 +15,19 @@ using Discord.WebSocket; namespace Discord.Rest { + /// A client which invokes Discord's REST API. public class DiscordRestClient : IDiscordClient { private readonly object _eventLock = new object(); + /// Fired whenever a message is logged. public event Func Log { add { _logEvent.Add(value); } remove { _logEvent.Remove(value); } } private readonly AsyncEvent> _logEvent = new AsyncEvent>(); + /// Fired whenever the client logs in. public event Func LoggedIn { add { _loggedInEvent.Add(value); } remove { _loggedInEvent.Remove(value); } } private readonly AsyncEvent> _loggedInEvent = new AsyncEvent>(); + /// Fired whenever the client logs out. public event Func LoggedOut { add { _loggedOutEvent.Add(value); } remove { _loggedOutEvent.Remove(value); } } private readonly AsyncEvent> _loggedOutEvent = new AsyncEvent>(); @@ -33,12 +37,15 @@ namespace Discord.Rest private bool _isFirstLogSub; internal bool _isDisposed; + /// The API client used for making API calls. public API.DiscordRestApiClient ApiClient { get; } internal LogManager LogManager { get; } + /// The current login state of the client. public LoginState LoginState { get; private set; } /// Creates a new REST-only discord client. public DiscordRestClient() : this(new DiscordRestConfig()) { } + /// Creates a new REST-only discord client. public DiscordRestClient(DiscordRestConfig config) : this(config, CreateApiClient(config)) { } /// Creates a new REST-only discord client. internal DiscordRestClient(DiscordRestConfig config, API.DiscordRestApiClient client) @@ -103,6 +110,7 @@ namespace Discord.Rest await _loggedInEvent.InvokeAsync().ConfigureAwait(false); } + /// Validates a token with the given type. protected virtual async Task ValidateTokenAsync(TokenType tokenType, string token) { try @@ -121,6 +129,7 @@ namespace Discord.Rest throw new ArgumentException("Token validation failed", nameof(token), ex); } } + /// A Promise for when the client successfully logs in. protected virtual Task OnLoginAsync(TokenType tokenType, string token) => Task.CompletedTask; @@ -149,6 +158,7 @@ namespace Discord.Rest await _loggedOutEvent.InvokeAsync().ConfigureAwait(false); } + /// A Promise for when the client successfully logs out. protected virtual Task OnLogoutAsync() => Task.CompletedTask; /// diff --git a/src/Discord.Net/Rest/DiscordRestConfig.cs b/src/Discord.Net/Rest/DiscordRestConfig.cs index 8dee72231..e6b7056f6 100644 --- a/src/Discord.Net/Rest/DiscordRestConfig.cs +++ b/src/Discord.Net/Rest/DiscordRestConfig.cs @@ -2,8 +2,10 @@ namespace Discord.Rest { + /// A set of common configuration options for REST clients. public class DiscordRestConfig : DiscordConfig { + /// Gets the user agent used in REST API calls public static string UserAgent { get; } = $"DiscordBot (https://github.com/RogueException/Discord.Net, v{Version})"; internal const int RestTimeout = 10000;