Merge pull request #47 from pimanac/documentation

Documentation!

Author: CrustyJew

RedditSharp/AuthProvider.cs

@@ -168,7 +168,13 @@ public string GetOAuthToken(string username, string password)
             }
             throw new AuthenticationException("Could not log in.");
         }
-		
+
+        /// <summary>
+        /// revokes an oauth token
+        /// </summary>
+        /// <param name="token">The oauth token..</param>
+        /// <param name="isRefresh">Set to true for refresh token.</param>
+        /// <returns>The access token</returns>
         public void RevokeToken(string token, bool isRefresh)
         {
             string tokenType = isRefresh ? "refresh_token" : "access_token";

RedditSharp/BotWebAgent.cs

@@ -14,8 +14,19 @@ public class BotWebAgent : WebAgent
         private string Username;
         private string Password;
 
+        /// <summary>
+        /// DateTime the token expires.
+        /// </summary>
         public DateTime TokenValidTo { get; set; }
 
+        /// <summary>
+        /// A web agent using reddit's OAuth interface.
+        /// </summary>
+        /// <param name="username">The username.</param>
+        /// <param name="password">The user's password.</param>
+        /// <param name="clientId">Granted by reddit as part of app.</param>
+        /// <param name="clientSecret">Granted by reddit as part of app.</param>
+        /// <param name="redirectUri">Selected as part of app. Reddit will send users back here.</param>
         public BotWebAgent(string username, string password, string clientID, string clientSecret, string redirectURI)
         {
             Username = username;
@@ -27,6 +38,7 @@ public BotWebAgent(string username, string password, string clientID, string cli
             GetNewToken();
         }
 
+        /// <inheritdoc/>
         public override HttpWebRequest CreateRequest(string url, string method)
         {
             //add 5 minutes for clock skew to ensure requests succeed 
@@ -37,6 +49,7 @@ public override HttpWebRequest CreateRequest(string url, string method)
             return base.CreateRequest(url, method);
         }
 
+        /// <inheritdoc/>
         protected override HttpWebRequest CreateRequest(Uri uri, string method)
         {
             //add 5 minutes for clock skew to ensure requests succeed

RedditSharp/Catchpha/Captcha.cs

@@ -6,7 +6,14 @@ public struct Captcha
     {
         private const string UrlFormat = "http://www.reddit.com/captcha/{0}";
 
+        /// <summary>
+        /// Captcha Id.
+        /// </summary>
         public readonly string Id;
+
+        /// <summary>
+        /// Captcha url.
+        /// </summary>
         public readonly Uri Url;
 
         internal Captcha(string id)

RedditSharp/Catchpha/CaptchaResponse.cs

@@ -2,8 +2,14 @@
 {
     public class CaptchaResponse
     {
+        /// <summary>
+        /// Captcha answer.
+        /// </summary>
         public readonly string Answer;
 
+        /// <summary>
+        /// Set to true to cancel.
+        /// </summary>
         public bool Cancel { get { return string.IsNullOrEmpty(Answer); } }
 
         public CaptchaResponse(string answer = null)

RedditSharp/Data/LinkData.cs

@@ -2,9 +2,15 @@
 {
     internal class LinkData : SubmitData
     {
+        /// <summary>
+        /// Used for redirects.
+        /// </summary>
         [RedditAPIName("extension")]
         internal string Extension { get; set; }
 
+        /// <summary>
+        /// Url of the link.
+        /// </summary>
         [RedditAPIName("url")]
         internal string URL { get; set; }
 

RedditSharp/Data/SubmitData.cs

@@ -2,27 +2,52 @@ namespace RedditSharp
 {
     internal abstract class SubmitData
     {
+        /// <summary>
+        /// Should be set to "json"
+        /// </summary>
         [RedditAPIName("api_type")]
         internal string APIType { get; set; }
 
+        /// <summary>
+        /// One of "link", "self" or "image"
+        /// </summary>
         [RedditAPIName("kind")]
         internal string Kind { get; set; }
 
+        /// <summary>
+        /// Name of the subreddit to which you are submitting.
+        /// </summary>
         [RedditAPIName("sr")]
         internal string Subreddit { get; set; }
 
+        /// <summary>
+        /// Logged in users modhash.
+        /// </summary>
         [RedditAPIName("uh")]
         internal string UserHash { get; set; }
 
+        /// <summary>
+        /// Title of the submission.  Maximum 300 characters.
+        /// </summary>
         [RedditAPIName("title")]
         internal string Title { get; set; }
 
+        /// <summary>
+        /// Captcha ident.
+        /// </summary>
         [RedditAPIName("iden")]
         internal string Iden { get; set; }
 
+        /// <summary>
+        /// Captcha.
+        /// </summary>
         [RedditAPIName("captcha")]
         internal string Captcha { get; set; }
 
+        /// <summary>
+        /// If a link with the same URL has already been submitted to the specified
+        /// subreddit an error will be returned unless resubmit is true.
+        /// </summary>
         [RedditAPIName("resubmit")]
         internal bool Resubmit { get; set; }
 

RedditSharp/Data/TextData.cs

@@ -2,6 +2,9 @@
 {
     internal class TextData : SubmitData
     {
+        /// <summary>
+        /// Markdown text of the self post.
+        /// </summary>
         [RedditAPIName("text")]
         internal string Text { get; set; }
 

RedditSharp/Domain.cs

@@ -17,9 +17,15 @@ public class Domain
         [JsonIgnore]
         private IWebAgent WebAgent { get; set; }
 
+        /// <summary>
+        /// Domain name
+        /// </summary>
         [JsonIgnore]
         public string Name { get; set; }
 
+        /// <summary>
+        /// Get a <see cref="Listing{T}"/> of posts made for this domain.
+        /// </summary>
         public Listing<Post> Posts
         {
             get
@@ -28,6 +34,9 @@ public Listing<Post> Posts
             }
         }
 
+        /// <summary>
+        /// Get a <see cref="Listing{T}"/> of posts made for this domain that are in the new queue.
+        /// </summary>
         public Listing<Post> New
         {
             get
@@ -36,6 +45,9 @@ public Listing<Post> New
             }
         }
 
+        /// <summary>
+        /// Get a <see cref="Listing{T}"/> of posts made for this domain that are in the hot queue.
+        /// </summary>
         public Listing<Post> Hot
         {
             get
@@ -51,6 +63,7 @@ protected internal Domain(Reddit reddit, Uri domain, IWebAgent webAgent)
             Name = domain.Host;
         }
 
+        /// <inheritdoc/>
         public override string ToString()
         {
             return "/domain/" + Name;

RedditSharp/Flairs/FlairTemplate.cs

@@ -10,18 +10,33 @@ public enum FlairPosition
     }
     public class UserFlairTemplate // TODO: Consider using this class to set templates as well
     {
+        /// <summary>
+        /// Flair text.
+        /// </summary>
         [JsonProperty("flair_text")]
         public string Text { get; set; }
 
+        /// <summary>
+        /// Flair clss class.
+        /// </summary>
         [JsonProperty("flair_css_class")]
         public string CssClass { get; set; }
 
+        /// <summary>
+        /// Flair template id.
+        /// </summary>
         [JsonProperty("flair_template_id")]
         public string TemplateId { get; set; }
 
+        /// <summary>
+        /// Set to true if this is user editable.
+        /// </summary>
         [JsonProperty("flair_text_editable")]
         public bool IsEditable { get; set; }
 
+        /// <summary>
+        /// Position of the flair left or right.
+        /// </summary>
         [JsonProperty("flair_position")]
         [JsonConverter(typeof(StringEnumConverter))]
         public FlairPosition FlairPosition { get; set; }

RedditSharp/Moderator Actions/ModeratorPermission.cs

@@ -8,13 +8,37 @@ namespace RedditSharp
     [Flags]
     public enum ModeratorPermission
     {
+        /// <summary>
+        /// No permissions.
+        /// </summary>
         None   = 0x00,
+        /// <summary>
+        /// access permissions.
+        /// </summary>
         Access = 0x01,
+        /// <summary>
+        /// Subreddit config.
+        /// </summary>
         Config = 0x02,
+        /// <summary>
+        /// Flair management.
+        /// </summary>
         Flair  = 0x04,
+        /// <summary>
+        /// Modmail.
+        /// </summary>
         Mail   = 0x08,
+        /// <summary>
+        /// Moderate posts.
+        /// </summary>
         Posts  = 0x10,
+        /// <summary>
+        /// Edit / view protected wiki paes.
+        /// </summary>
         Wiki   = 0x20,
+        /// <summary>
+        /// All permissions.
+        /// </summary>
         All    = Access | Config | Flair | Mail | Posts | Wiki
     }