add comments to audit module (#7635)

* add comments to audit module

* Improve it as @DanielStolt  suggest

* Apply trailing periods consistently

src/Orchard.Web/Modules/Orchard.AuditTrail/Models/AuditTrailEventRecord.cs

@@ -2,21 +2,63 @@
 using Orchard.Data.Conventions;
 
 namespace Orchard.AuditTrail.Models {
+
+    /// <summary>
+    /// Audit Trail Event Record in the database.
+    /// </summary>
     public class AuditTrailEventRecord {
         public virtual int Id { get; set; }
+
+        /// <summary>
+        /// The time when the event occurred.
+        /// </summary>
         public virtual DateTime CreatedUtc { get; set; }
+
+        /// <summary>
+        /// The user name of the user who caused the event to occur.
+        /// </summary>
         public virtual string UserName { get; set; }
+
+        /// <summary>
+        /// The name of the event.
+        /// </summary>
         public virtual string EventName { get; set; }
+
+        /// <summary>
+        /// The full name of the event.
+        /// </summary>
         public virtual string FullEventName { get; set; }
+
+        /// <summary>
+        /// The category the event belongs to.
+        /// </summary>
         public virtual string Category { get; set; }
-        
+
+        /// <summary>
+        /// The data of the event.
+        /// </summary>
         [StringLengthMax]
         public virtual string EventData { get; set; }
+
+        /// <summary>
+        /// The filter key of the event.
+        /// </summary>
         public virtual string EventFilterKey { get; set; }
+
+        /// <summary>
+        /// The filter data of the event.
+        /// </summary>
         public virtual string EventFilterData { get; set; }
 
+        /// <summary>
+        /// The comment of the event.
+        /// </summary>
         [StringLengthMax]
         public virtual string Comment { get; set; }
+
+        /// <summary>
+        /// The IP address of the user who caused the event to occur.
+        /// </summary>
         public virtual string ClientIpAddress { get; set; }
     }
 }

src/Orchard.Web/Modules/Orchard.AuditTrail/Models/AuditTrailEventRecordResult.cs

@@ -1,6 +1,18 @@
 namespace Orchard.AuditTrail.Models {
+
+    /// <summary>
+    /// The created audit trail event result
+    /// </summary>
     public class AuditTrailEventRecordResult {
+
+        /// <summary>
+        /// The created <see cref="AuditTrailEventRecord"/> 
+        /// </summary>
         public AuditTrailEventRecord Record { get; set; }
+
+        /// <summary>
+        /// Determines whether AuditTrailEventRecordResult is disabled for <see cref="AuditTrailEventRecord"/> .
+        /// </summary>
         public bool IsDisabled { get; set; }
     }
 }

src/Orchard.Web/Modules/Orchard.AuditTrail/Services/AuditTrailManager.cs

@@ -16,6 +16,10 @@ using Orchard.Services;
 using Orchard.Settings;
 
 namespace Orchard.AuditTrail.Services {
+
+    /// <summary>
+    /// Manage the audit trail.
+    /// </summary>
     public class AuditTrailManager : Component, IAuditTrailManager {
         private readonly IRepository<AuditTrailEventRecord> _auditTrailRepository;
         private readonly IAuditTrailEventProvider _providers;
@@ -52,6 +56,14 @@ namespace Orchard.AuditTrail.Services {
             _clientHostAddressAccessor = clientHostAddressAccessor;
         }
 
+        /// <summary>
+        /// Gets a page of event records from the audit trail.
+        /// </summary>
+        /// <param name="page">The page number to get records from.</param>
+        /// <param name="pageSize">The number of records to get.</param>
+        /// <param name="orderBy">The value to order by.</param>
+        /// <param name="filters">Optional. An object to filter the records on.</param>
+        /// <returns>A page of event records.</returns>
         public IPageOfItems<AuditTrailEventRecord> GetRecords(
             int page,
             int pageSize,
@@ -102,10 +114,20 @@ namespace Orchard.AuditTrail.Services {
             };
         }
 
+        /// <summary>
+        /// Gets a single event record from the audit trail by ID.
+        /// </summary>
+        /// <param name="id">The event record ID.</param>
+        /// <returns>A single event record.</returns>
         public AuditTrailEventRecord GetRecord(int id) {
             return _auditTrailRepository.Get(id);
         }
 
+        /// <summary>
+        /// Builds a shape tree of filter displays.
+        /// </summary>
+        /// <param name="filters">Input for each filter builder.</param>
+        /// <returns>A tree of shapes.</returns>
         public dynamic BuildFilterDisplay(Filters filters) {
             var filterDisplay = (dynamic)_shapeFactory.Create("AuditTrailFilter");
             var filterDisplayContext = new DisplayFilterContext(_shapeFactory, filters, filterDisplay);
@@ -123,6 +145,17 @@ namespace Orchard.AuditTrail.Services {
             return filterDisplay;
         }
 
+        /// <summary>
+        /// Records an audit trail event.
+        /// </summary>
+        /// <typeparam name="T">The audit trail event provider type to determine the scope of the event name.</typeparam>
+        /// <param name="eventName">The shorthand name of the event</param>
+        /// <param name="user">The user to associate with the event. This is typically the currently loggedin user.</param>
+        /// <param name="properties">A property bag of custom event data that could be useful for <see cref="IAuditTrailEventHandler"/> implementations. These values aren't stored. Use the eventData parameter to persist additional data with the event.</param>
+        /// <param name="eventData">A property bag of custom event data that will be stored with the event record.</param>
+        /// <param name="eventFilterKey">The name of a custom key to use when filtering events.</param>
+        /// <param name="eventFilterData">The value of a custom filter key to filter on.</param>
+        /// <returns>The created audit trail event record if the specified event was not disabled.</returns>
         public AuditTrailEventRecordResult CreateRecord<T>(string eventName, IUser user, IDictionary<string, object> properties = null, IDictionary<string, object> eventData = null, string eventFilterKey = null, string eventFilterData = null) where T : IAuditTrailEventProvider {
             var eventDescriptor = DescribeEvent<T>(eventName);
             if (!IsEventEnabled(eventDescriptor))
@@ -165,26 +198,49 @@ namespace Orchard.AuditTrail.Services {
             };
         }
 
+        /// <summary>
+        /// Describes all audit trail events provided by the system.
+        /// </summary>
+        /// <returns>A list of audit trail category descriptors.</returns>
         public IEnumerable<AuditTrailCategoryDescriptor> DescribeCategories() {
             var context = DescribeProviders();
             return context.Describe();
         }
 
+        /// <summary>
+        /// Describes all audit trail event providers.
+        /// </summary>
         public DescribeContext DescribeProviders() {
             var context = new DescribeContext();
             _providers.Describe(context);
             return context;
         }
 
+        /// <summary>
+        /// Describes a single audit trail event.
+        /// </summary>
+        /// <param name="record">The audit trail event record for which to find its descriptor.</param>
+        /// <returns>A single audit trail event descriptor.</returns>
         public AuditTrailEventDescriptor DescribeEvent(AuditTrailEventRecord record) {
             return DescribeEvent(record.FullEventName) ?? AuditTrailEventDescriptor.Basic(record);
         }
 
+        /// <summary>
+        /// Describes a single audit trail event.
+        /// </summary>
+        /// <typeparam name="T">The scope of the specified event name.</typeparam>
+        /// <param name="eventName">The shorthand name of the event.</param>
+        /// <returns>A single audit trail event descriptor.</returns>
         public AuditTrailEventDescriptor DescribeEvent<T>(string eventName) where T : IAuditTrailEventProvider {
             var fullyQualifiedEventName = EventNameExtensions.GetFullyQualifiedEventName<T>(eventName);
             return DescribeEvent(fullyQualifiedEventName);
         }
 
+        /// <summary>
+        /// Describes a single audit trail event.
+        /// </summary>
+        /// <param name="fullyQualifiedEventName">The fully qualified event name to describe.</param>
+        /// <returns>A single audit trail event descriptor.</returns>
         public AuditTrailEventDescriptor DescribeEvent(string fullyQualifiedEventName) {
             var categoryDescriptors = DescribeCategories();
             var eventDescriptorQuery =

src/Orchard.Web/Modules/Orchard.AuditTrail/Services/EventDataSerializer.cs

@@ -5,7 +5,17 @@ using Newtonsoft.Json;
 using Orchard.Logging;
 
 namespace Orchard.AuditTrail.Services {
+
+    /// <summary>
+    /// A service responsible for serializing and deserializing audit trail event data.
+    /// </summary>
     public class EventDataSerializer : Component, IEventDataSerializer {
+
+        /// <summary>
+        /// Serialize event data.
+        /// </summary>
+        /// <param name="eventData">eventData to be serialized.</param>
+        /// <returns>The serialized data.</returns>
         public string Serialize(IDictionary<string, object> eventData) {
             try {
                 var json = JsonConvert.SerializeObject(eventData, Formatting.None);
@@ -18,6 +28,11 @@ namespace Orchard.AuditTrail.Services {
             return null;
         }
 
+        /// <summary>
+        /// Deserialize event data.
+        /// </summary>
+        /// <param name="eventData">eventData to be deserialized.</param>
+        /// <returns>The deserialized generic dictionary</returns>
         public IDictionary<string, object> Deserialize(string eventData) {
             if (String.IsNullOrWhiteSpace(eventData))
                 return new Dictionary<string, object>();

src/Orchard.Web/Modules/Orchard.AuditTrail/Services/IAuditTrailManager.cs

@@ -6,7 +6,12 @@ using Orchard.Collections;
 using Orchard.Security;
 
 namespace Orchard.AuditTrail.Services {
+
+    /// <summary>
+    /// Manage the audit trail.
+    /// </summary>
     public interface IAuditTrailManager : IDependency {
+
         /// <summary>
         /// Gets a page of event records from the audit trail.
         /// </summary>

src/Orchard.Web/Modules/Orchard.AuditTrail/Services/IEventDataSerializer.cs

@@ -1,8 +1,24 @@
 using System.Collections.Generic;
 
 namespace Orchard.AuditTrail.Services {
+
+    /// <summary>
+    /// A service responsible for serializing and deserializing audit trail event data.
+    /// </summary>
     public interface IEventDataSerializer : IDependency {
+
+        /// <summary>
+        /// Serialize event data.
+        /// </summary>
+        /// <param name="eventData">eventData to be serialized.</param>
+        /// <returns>The serialized data.</returns>
         string Serialize(IDictionary<string, object> eventData);
+
+        /// <summary>
+        /// Deserialize event data.
+        /// </summary>
+        /// <param name="eventData">eventData to be deserialized.</param>
+        /// <returns>The deserialized generic dictionary</returns>
         IDictionary<string, object> Deserialize(string eventData);
     }
 }