Adding inline documentation to reports

src/Orchard/Reports/ReportExtentions.cs

@@ -2,12 +2,32 @@
 using Orchard.Reports.Services;
 
 public static class ReportExtentions {
+    /// <summary>
+    /// Adds a new report entry of type information to a report that was previously registered.
+    /// </summary>
+    /// <seealso cref="Register()"/>
+    /// <param name="reportKey">Key, i.e. technical name of the report. Should be the same as the one used when registering the report.</param>
+    /// <param name="message">The message to include in the entry.</param>
     public static void Information(this IReportsCoordinator reportCoordinator, string reportKey, string message) {
         reportCoordinator.Add(reportKey, ReportEntryType.Information, message);
     }
+
+    /// <summary>
+    /// Adds a new report entry of type warning to a report that was previously registered.
+    /// </summary>
+    /// <seealso cref="Register()"/>
+    /// <param name="reportKey">Key, i.e. technical name of the report. Should be the same as the one used when registering the report.</param>
+    /// <param name="message">The message to include in the entry.</param>
     public static void Warning(this IReportsCoordinator reportCoordinator, string reportKey, string message) {
         reportCoordinator.Add(reportKey, ReportEntryType.Warning, message);
     }
+
+    /// <summary>
+    /// Adds a new report entry of type error to a report that was previously registered.
+    /// </summary>
+    /// <seealso cref="Register()"/>
+    /// <param name="reportKey">Key, i.e. technical name of the report. Should be the same as the one used when registering the report.</param>
+    /// <param name="message">The message to include in the entry.</param>
     public static void Error(this IReportsCoordinator reportCoordinator, string reportKey, string message) {
         reportCoordinator.Add(reportKey, ReportEntryType.Error, message);
     }

src/Orchard/Reports/Services/IReportsCoordinator.cs

@@ -1,6 +1,30 @@
 namespace Orchard.Reports.Services {
+    /// <summary>
+    /// Exposes a simplified interface for creating reports. Reports provide user-accessible log-like functionality.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="Orchard.Reports.Services.IReportsManager"/> can be used too to create reports directly.
+    /// </remarks>
     public interface IReportsCoordinator : IDependency {
+        /// <summary>
+        /// Adds a new report entry to a report that was previously registered.
+        /// </summary>
+        /// <remarks>
+        /// Entries can be only added to a report that was previously registered through Register().
+        /// </remarks>
+        /// <seealso cref="Register()"/>
+        /// <param name="reportKey">Key, i.e. technical name of the report. Should be the same as the one used when registering the report.</param>
+        /// <param name="type">Type of the entry.</param>
+        /// <param name="message">The message to include in the entry.</param>
         void Add(string reportKey, ReportEntryType type, string message);
+
+        /// <summary>
+        /// Registers a new report so entries can be added to it.
+        /// </summary>
+        /// <param name="reportKey">Key, i.e. technical name of the report.</param>
+        /// <param name="activityName">Name of the activity the report is about (e.g. "Upgrade").</param>
+        /// <param name="title">A title better describing what the report is about (e.g. "Migrating routes of Pages, Blog Posts").</param>
+        /// <returns>The report's numerical ID.</returns>
         int Register(string reportKey, string activityName, string title);
     }
 }

src/Orchard/Reports/Services/IReportsManager.cs

@@ -1,6 +1,12 @@
 using System.Collections.Generic;
 
 namespace Orchard.Reports.Services {
+    /// <summary>
+    /// Service for handling reports. Reports provide user-accessible log-like functionality.
+    /// </summary>
+    /// <remarks>
+    /// You can use <see cref="Orchard.Reports.Services.IReportsCoordinator"/> to create reports through a simplified interface.
+    /// </remarks>
     public interface IReportsManager : ISingletonDependency {
         void Add(int reportId, ReportEntryType type, string message);
         int CreateReport(string title, string activityName);

src/Orchard/Reports/Services/IReportsPersister.cs

@@ -1,6 +1,12 @@
 using System.Collections.Generic;
 
 namespace Orchard.Reports.Services {
+    /// <summary>
+    /// Defines a service that can be used to persist reports.
+    /// </summary>
+    /// <remarks>
+    /// Implementations of this interface are commonly used from <see cref="Orchard.Reports.Services.IReportsManager"/> implementations.
+    /// </remarks>
     public interface IReportsPersister : IDependency {
         IEnumerable<Report> Fetch();
         void Save(IEnumerable<Report> reports);