From 924da7dec768551f64ef15ad5a508d100f481373 Mon Sep 17 00:00:00 2001
From: Lombiq <registrator@lombiq.com>
Date: Fri, 14 Feb 2014 14:30:53 +0100
Subject: [PATCH] Adding inline documentation to reports

---
 src/Orchard/Reports/ReportExtentions.cs       | 20 ++++++++++++++++
 .../Reports/Services/IReportsCoordinator.cs   | 24 +++++++++++++++++++
 .../Reports/Services/IReportsManager.cs       |  6 +++++
 .../Reports/Services/IReportsPersister.cs     |  6 +++++
 4 files changed, 56 insertions(+)

diff --git a/src/Orchard/Reports/ReportExtentions.cs b/src/Orchard/Reports/ReportExtentions.cs
index 05b898058..2ebb2ff01 100644
--- a/src/Orchard/Reports/ReportExtentions.cs
+++ b/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);
     }
diff --git a/src/Orchard/Reports/Services/IReportsCoordinator.cs b/src/Orchard/Reports/Services/IReportsCoordinator.cs
index d8104b89b..659f86f91 100644
--- a/src/Orchard/Reports/Services/IReportsCoordinator.cs
+++ b/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);
     }
 }
diff --git a/src/Orchard/Reports/Services/IReportsManager.cs b/src/Orchard/Reports/Services/IReportsManager.cs
index 36ff65038..f2006adf4 100644
--- a/src/Orchard/Reports/Services/IReportsManager.cs
+++ b/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);
diff --git a/src/Orchard/Reports/Services/IReportsPersister.cs b/src/Orchard/Reports/Services/IReportsPersister.cs
index d1dd3238f..b79cd9e3b 100644
--- a/src/Orchard/Reports/Services/IReportsPersister.cs
+++ b/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);