Merge pull request #42 from asbjornu/documentation

Adds XML documentation to all public classes, properties and methods, reducing the number of warnings from 49 to 3. The documentation should also be useful for anyone using the SharpRaven library.

Author: asbjornu

SharpRaven/Data/ExceptionFrame.cs

@@ -3,37 +3,106 @@
 using Newtonsoft.Json;
 
 namespace SharpRaven.Data {
+    /// <summary>
+    /// Represents Sentry's version of <see cref="System.Diagnostics.StackFrame" />.
+    /// </summary>
     public class ExceptionFrame {
+        /// <summary>
+        /// Gets or sets the absolute path.
+        /// </summary>
+        /// <value>
+        /// The absolute path.
+        /// </value>
         [JsonProperty(PropertyName = "abs_path")]
         public string AbsolutePath { get; set; }
 
+        /// <summary>
+        /// Gets or sets the filename.
+        /// </summary>
+        /// <value>
+        /// The filename.
+        /// </value>
         [JsonProperty(PropertyName = "filename")]
         public string Filename { get; set; }
 
+        /// <summary>
+        /// Gets or sets the module.
+        /// </summary>
+        /// <value>
+        /// The module.
+        /// </value>
         [JsonProperty(PropertyName = "module")]
         public string Module { get; set; }
 
+        /// <summary>
+        /// Gets or sets the function.
+        /// </summary>
+        /// <value>
+        /// The function.
+        /// </value>
         [JsonProperty(PropertyName = "function")]
         public string Function { get; set; }
 
+        /// <summary>
+        /// Gets or sets the vars.
+        /// </summary>
+        /// <value>
+        /// The vars.
+        /// </value>
         [JsonProperty(PropertyName = "vars")]
         public Dictionary<string, string> Vars { get; set; }
 
+        /// <summary>
+        /// Gets or sets the preference context.
+        /// </summary>
+        /// <value>
+        /// The preference context.
+        /// </value>
         [JsonProperty(PropertyName = "pre_context")]
         public List<string> PreContext { get; set; }
 
+        /// <summary>
+        /// Gets or sets the source.
+        /// </summary>
+        /// <value>
+        /// The source.
+        /// </value>
         [JsonProperty(PropertyName = "context_line")]
         public string Source { get; set; }
 
+        /// <summary>
+        /// Gets or sets the line number.
+        /// </summary>
+        /// <value>
+        /// The line number.
+        /// </value>
         [JsonProperty(PropertyName = "lineno")]
         public int LineNumber { get; set; }
 
+        /// <summary>
+        /// Gets or sets the column number.
+        /// </summary>
+        /// <value>
+        /// The column number.
+        /// </value>
         [JsonProperty(PropertyName = "colno")]
         public int ColumnNumber { get; set; }
 
+        /// <summary>
+        /// Gets or sets a value indicating whether [information application].
+        /// </summary>
+        /// <value>
+        /// <c>true</c> if [information application]; otherwise, <c>false</c>.
+        /// </value>
         [JsonProperty(PropertyName = "in_app")]
         public bool InApp { get; set; }
 
+        /// <summary>
+        /// Gets or sets the post context.
+        /// </summary>
+        /// <value>
+        /// The post context.
+        /// </value>
         [JsonProperty(PropertyName = "post_context")]
         public List<string> PostContext { get; set; }
     }

SharpRaven/Data/JsonPacket.cs

@@ -8,8 +8,15 @@
 
 namespace SharpRaven.Data
 {
+    /// <summary>
+    /// Represents the JSON packet that is transmitted to Sentry.
+    /// </summary>
     public class JsonPacket
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="JsonPacket"/> class.
+        /// </summary>
+        /// <param name="project">The project.</param>
         public JsonPacket(string project)
         {
             // Get assemblies.
@@ -45,6 +52,11 @@ public JsonPacket(string project)
         }
 
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="JsonPacket"/> class.
+        /// </summary>
+        /// <param name="project">The project.</param>
+        /// <param name="e">The decimal.</param>
         public JsonPacket(string project, Exception e)
         {
             Message = e.Message;
@@ -156,25 +168,47 @@ public JsonPacket(string project, Exception e)
 
         /// <summary>
         /// A list of relevant modules (libraries) and their versions.
-        /// 
         /// Automated to report all modules currently loaded in project.
         /// </summary>
+        /// <value>
+        /// The modules.
+        /// </value>
         [JsonProperty(PropertyName = "modules", NullValueHandling = NullValueHandling.Ignore)]
         public List<Module> Modules { get; set; }
 
+        /// <summary>
+        /// Gets or sets the exceptions.
+        /// </summary>
+        /// <value>
+        /// The exceptions.
+        /// </value>
         [JsonProperty(PropertyName = "exception", NullValueHandling = NullValueHandling.Ignore)]
         public List<SentryException> Exceptions { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="SentryRequest"/> object, containing information about the HTTP request.
+        /// </summary>
+        /// <value>
+        /// The <see cref="SentryRequest"/> object, containing information about the HTTP request.
+        /// </value>
         [JsonProperty(PropertyName = "request", NullValueHandling = NullValueHandling.Ignore)]
         public SentryRequest Request { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="SentryUser"/> object, which describes the authenticated User for a request.
+        /// </summary>
+        /// <value>
+        /// The <see cref="SentryUser"/> object, which describes the authenticated User for a request.
+        /// </value>
         [JsonProperty(PropertyName = "user", NullValueHandling = NullValueHandling.Ignore)]
         public SentryUser User { get; set; }
 
         /// <summary>
-        /// Turn into a JSON string.
+        /// Converts the <see cref="JsonPacket"/> into a JSON string.
         /// </summary>
-        /// <returns>json string</returns>
+        /// <returns>
+        /// The <see cref="JsonPacket"/> as a JSON string.
+        /// </returns>
         public override string ToString()
         {
             return JsonConvert.SerializeObject(this);

SharpRaven/Data/SentryException.cs

@@ -2,6 +2,9 @@
 using Newtonsoft.Json;
 
 namespace SharpRaven.Data {
+    /// <summary>
+    /// Represents Sentry's version of an <see cref="Exception"/>.
+    /// </summary>
     public class SentryException {
         /// <summary>
         /// The type of exception.
@@ -28,6 +31,10 @@ public class SentryException {
         public SentryStacktrace Stacktrace { get; set; }
 
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SentryException"/> class.
+        /// </summary>
+        /// <param name="e">The <see cref="Exception"/>.</param>
         public SentryException(Exception e) {
             this.Module = e.Source;
             this.Type = e.Message;

SharpRaven/Data/SentryRequest.cs

@@ -41,9 +41,21 @@ private bool HasHttpContext
         }
 
 
+        /// <summary>
+        /// Gets or sets the URL of the HTTP request.
+        /// </summary>
+        /// <value>
+        /// The URL of the HTTP request.
+        /// </value>
         [JsonProperty(PropertyName = "url", NullValueHandling = NullValueHandling.Ignore)]
         public string Url { get; set; }
 
+        /// <summary>
+        /// Gets or sets the method of the HTTP request.
+        /// </summary>
+        /// <value>
+        /// The method of the HTTP request.
+        /// </value>
         [JsonProperty(PropertyName = "method", NullValueHandling = NullValueHandling.Ignore)]
         public string Method { get; set; }
 
@@ -56,12 +68,30 @@ private bool HasHttpContext
         [JsonProperty(PropertyName = "data", NullValueHandling = NullValueHandling.Ignore)]
         public object Data { get; set; }
 
+        /// <summary>
+        /// Gets or sets the query string.
+        /// </summary>
+        /// <value>
+        /// The query string.
+        /// </value>
         [JsonProperty(PropertyName = "query_string", NullValueHandling = NullValueHandling.Ignore)]
         public string QueryString { get; set; }
 
+        /// <summary>
+        /// Gets or sets the cookies.
+        /// </summary>
+        /// <value>
+        /// The cookies.
+        /// </value>
         [JsonProperty(PropertyName = "cookies", NullValueHandling = NullValueHandling.Ignore)]
         public IDictionary<string, string> Cookies { get; set; }
 
+        /// <summary>
+        /// Gets or sets the headers.
+        /// </summary>
+        /// <value>
+        /// The headers.
+        /// </value>
         [JsonProperty(PropertyName = "headers", NullValueHandling = NullValueHandling.Ignore)]
         public IDictionary<string, string> Headers { get; set; }
 
@@ -76,13 +106,25 @@ private bool HasHttpContext
         public IDictionary<string, string> Environment { get; set; }
 
 
+        /// <summary>
+        /// Gets the request.
+        /// </summary>
+        /// <returns>
+        /// If an HTTP contest is available, an instance of <see cref="SentryRequest"/>, otherwise <c>null</c>.
+        /// </returns>
         public static SentryRequest GetRequest()
         {
             var request = new SentryRequest();
             return request.HasHttpContext ? request : null;
         }
 
 
+        /// <summary>
+        /// Gets the user.
+        /// </summary>
+        /// <returns>
+        /// If an HTTP context is available, an instance of <see cref="SentryUser"/>, otherwise <c>null</c>.
+        /// </returns>
         public SentryUser GetUser()
         {
             if (!HasHttpContext)

SharpRaven/Data/SentryStacktrace.cs

@@ -7,7 +7,14 @@
 using Newtonsoft.Json;
 
 namespace SharpRaven.Data {
+    /// <summary>
+    /// Represents Sentry's version of an <see cref="Exception"/>'s stack trace.
+    /// </summary>
     public class SentryStacktrace {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SentryStacktrace"/> class.
+        /// </summary>
+        /// <param name="e">The decimal.</param>
         public SentryStacktrace(Exception e) {
             StackTrace trace = new StackTrace(e, true);
 
@@ -44,6 +51,12 @@ private static ExceptionFrame BuildExceptionFrame(StackFrame frame)
             };
         }
 
+        /// <summary>
+        /// Gets or sets the <see cref="Exception"/> frames.
+        /// </summary>
+        /// <value>
+        /// The <see cref="Exception"/> frames.
+        /// </value>
         [JsonProperty(PropertyName = "frames")]
         public ExceptionFrame[] Frames { get; set; }
 

SharpRaven/Data/SentryUser.cs

@@ -24,15 +24,39 @@ public SentryUser(IPrincipal principal)
         }
 
 
+        /// <summary>
+        /// Gets or sets the user's unique identifier.
+        /// </summary>
+        /// <value>
+        /// The unique identifier.
+        /// </value>
         [JsonProperty(PropertyName = "id", NullValueHandling = NullValueHandling.Ignore)]
         public string Id { get; set; }
 
+        /// <summary>
+        /// Gets or sets the user's username.
+        /// </summary>
+        /// <value>
+        /// The user's username.
+        /// </value>
         [JsonProperty(PropertyName = "username", NullValueHandling = NullValueHandling.Ignore)]
         public string Username { get; set; }
 
+        /// <summary>
+        /// Gets or sets the user's email address.
+        /// </summary>
+        /// <value>
+        /// The user's email address.
+        /// </value>
         [JsonProperty(PropertyName = "email", NullValueHandling = NullValueHandling.Ignore)]
         public string Email { get; set; }
 
+        /// <summary>
+        /// Gets or sets the user's IP address.
+        /// </summary>
+        /// <value>
+        /// The user's IP address.
+        /// </value>
         [JsonProperty(PropertyName = "ip_address", NullValueHandling = NullValueHandling.Ignore)]
         public string IpAddress { get; set; }
     }

SharpRaven/Logging/LogScrubber.cs

@@ -3,10 +3,22 @@
 using SharpRaven.Logging.Filters;
 
 namespace SharpRaven.Logging {
+    /// <summary>
+    /// Scrubs a JSON packet for sensitive information with <see cref="CreditCardFilter"/>, <see cref="PhoneNumberFilter"/> and <see cref="SocialSecurityFilter"/>.
+    /// </summary>
     public class LogScrubber : IScrubber {
+        /// <summary>
+        /// Gets the list of filters 
+        /// </summary>
+        /// <value>
+        /// The filters.
+        /// </value>
         public List<IFilter> Filters { get; private set; }
 
         // Default scrubber implementation.
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LogScrubber"/> class.
+        /// </summary>
         public LogScrubber() {
             Filters = new List<IFilter>();
 
@@ -18,6 +30,14 @@ public LogScrubber() {
             });
         }
 
+        /// <summary>
+        /// The main interface for scrubbing a JSON packet,
+        /// called before compression (if enabled)
+        /// </summary>
+        /// <param name="input">The serialized JSON packet is given here.</param>
+        /// <returns>
+        /// Scrubbed JSON packet.
+        /// </returns>
         public string Scrub(string input) {
             foreach (IFilter f in Filters) {
                 input = f.Filter(input);