SEBWIN-219: Documented types of core library.

SafeExamBrowser.Contracts/Behaviour/OperationModel/IOperationSequence.cs

@@ -11,15 +11,15 @@ using SafeExamBrowser.Contracts.UserInterface;
 namespace SafeExamBrowser.Contracts.Behaviour.OperationModel
 {
 	/// <summary>
-	/// A sequence of <see cref="IOperation"/>s which can be used for sequential procedures, e.g. the initialization &amp; finalization of an
-	/// application component. Each operation will be executed failsafe, i.e. the return value will indicate whether a procedure completed
-	/// successfully or not.
+	/// A sequence of <see cref="IOperation"/>s which can be used for sequential procedures, e.g. the initialization &amp; finalization of
+	/// an application component. Each operation will be executed failsafe, i.e. the return value will indicate whether a procedure
+	/// completed successfully or not.
 	/// 
-	/// The execution order of the individual operations (for an exemplary sequence initialized with operations A, B, C, D) is as follows:
+	/// Exemplary execution order for a sequence initialized with operations A, B, C, D:
 	/// 
-	/// <see cref="TryPerform"/>: The operations will be performed according to their initialized order (A -> B -> C -> D).
-	/// <see cref="TryRepeat"/>: The operations will be repeated according to their initialized order (A -> B -> C -> D).
-	/// <see cref="TryRevert"/>: The operations will be reverted according to the reversed initial order (D -> C -> B -> A).
+	/// <see cref="TryPerform"/>: A -> B -> C -> D.
+	/// <see cref="TryRepeat"/>: A -> B -> C -> D.
+	/// <see cref="TryRevert"/>: D -> C -> B -> A.
 	/// </summary>
 	public interface IOperationSequence
 	{
@@ -29,18 +29,20 @@ namespace SafeExamBrowser.Contracts.Behaviour.OperationModel
 		IProgressIndicator ProgressIndicator { set; }
 
 		/// <summary>
-		/// Tries to perform the operations of this sequence.
+		/// Tries to perform the operations of this sequence according to their initialized order. If any operation fails, the already
+		/// performed operations will be reverted.
 		/// </summary>
 		OperationResult TryPerform();
 
 		/// <summary>
-		/// Tries to repeat the operations of this sequence.
+		/// Tries to repeat the operations of this sequence according to their initialized order. If any operation fails, the already
+		/// performed operations will not be reverted.
 		/// </summary>
 		OperationResult TryRepeat();
 
 		/// <summary>
 		/// Tries to revert the operations of this sequence. Returns <c>true</c> if all operations were reverted without errors,
-		/// otherwise <c>false</c>.
+		/// otherwise <c>false</c>. The reversion of all operations will continue, even if one or multiple operations fail.
 		/// </summary>
 		bool TryRevert();
 	}

SafeExamBrowser.Contracts/Communication/ICommunicationHost.cs

@@ -11,7 +11,8 @@ namespace SafeExamBrowser.Contracts.Communication
 	public delegate void CommunicationEventHandler();
 
 	/// <summary>
-	/// Defines the common functionality for all communication hosts.
+	/// Defines the common functionality for all communication hosts. A communication host can be hosted by an application component to
+	/// allow for inter-process communication with other components (e.g. runtime -> client communication).
 	/// </summary>
 	public interface ICommunicationHost
 	{

SafeExamBrowser.Contracts/Communication/ICommunicationProxy.cs

@@ -11,7 +11,8 @@ using System;
 namespace SafeExamBrowser.Contracts.Communication
 {
 	/// <summary>
-	/// Defines the common functionality for all communication proxies.
+	/// Defines the common functionality for all communication proxies. A proxy is needed to be able to perform inter-process communication
+	/// with the <see cref="ICommunicationHost"/> of another application component.
 	/// </summary>
 	public interface ICommunicationProxy
 	{

SafeExamBrowser.Core/Behaviour/Operations/CommunicationOperation.cs

@@ -14,6 +14,10 @@ using SafeExamBrowser.Contracts.UserInterface;
 
 namespace SafeExamBrowser.Core.Behaviour.Operations
 {
+	/// <summary>
+	/// An operation to handle the lifetime of an <see cref="ICommunicationHost"/>. The host is started during <see cref="Perform"/>,
+	/// stopped and restarted during <see cref="Repeat"/> (if not running) and stopped during <see cref="Revert"/>.
+	/// </summary>
 	public class CommunicationOperation : IOperation
 	{
 		private ICommunicationHost host;

SafeExamBrowser.Core/Behaviour/Operations/DelayedInitializationOperation.cs

@@ -12,6 +12,11 @@ using SafeExamBrowser.Contracts.UserInterface;
 
 namespace SafeExamBrowser.Core.Behaviour.Operations
 {
+	/// <summary>
+	/// A wrapper operation to allow for a delayed (just-in-time) instantiation of an operation. Is useful when e.g. dependencies for a
+	/// certain operation are not available during execution of the composition root, but rather only after a preceding operation within
+	/// an <see cref="IOperationSequence"/> has finished.
+	/// </summary>
 	public class DelayedInitializationOperation : IOperation
 	{
 		private Func<IOperation> initialize;

SafeExamBrowser.Core/Behaviour/Operations/DelegateOperation.cs

@@ -12,6 +12,10 @@ using SafeExamBrowser.Contracts.UserInterface;
 
 namespace SafeExamBrowser.Core.Behaviour.Operations
 {
+	/// <summary>
+	/// A generic operation to allow for the (inline) definition of an operation via delegates. Useful if implementing a complete
+	/// <see cref="IOperation"/> would be an unnecessary overhead.
+	/// </summary>
 	public class DelegateOperation : IOperation
 	{
 		private Action perform;

SafeExamBrowser.Core/Behaviour/Operations/I18nOperation.cs

@@ -17,6 +17,9 @@ using SafeExamBrowser.Core.I18n;
 
 namespace SafeExamBrowser.Core.Behaviour.Operations
 {
+	/// <summary>
+	/// An operation to handle the initialization of an <see cref="IText"/> module with text data from the default directory.
+	/// </summary>
 	public class I18nOperation : IOperation
 	{
 		private ILogger logger;

SafeExamBrowser.Core/Behaviour/Operations/OperationSequence.cs

@@ -15,6 +15,9 @@ using SafeExamBrowser.Contracts.UserInterface;
 
 namespace SafeExamBrowser.Core.Behaviour.Operations
 {
+	/// <summary>
+	/// Default implementation of the <see cref="IOperationSequence"/>.
+	/// </summary>
 	public class OperationSequence : IOperationSequence
 	{
 		private ILogger logger;

SafeExamBrowser.Core/Communication/BaseHost.cs

@@ -16,6 +16,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Communication
 {
+	/// <summary>
+	/// The base implementation of an <see cref="ICommunicationHost"/>. Runs the host on a new, separate thread.
+	/// </summary>
 	[ServiceBehavior(InstanceContextMode = InstanceContextMode.Single, ConcurrencyMode = ConcurrencyMode.Single)]
 	public abstract class BaseHost : ICommunication, ICommunicationHost
 	{

SafeExamBrowser.Core/Communication/BaseProxy.cs

@@ -16,6 +16,10 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Communication
 {
+	/// <summary>
+	/// Base implementation of an <see cref="ICommunicationProxy"/>. Automatically starts a ping mechanism with a timeout of
+	/// <see cref="ONE_MINUTE"/> once a connection was established.
+	/// </summary>
 	public abstract class BaseProxy : ICommunicationProxy
 	{
 		private const int ONE_MINUTE = 60000;

SafeExamBrowser.Core/Communication/ClientProxy.cs

@@ -14,6 +14,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Communication
 {
+	/// <summary>
+	/// Default implementation of the <see cref="IClientProxy"/>, to be used for communication with the client application component.
+	/// </summary>
 	public class ClientProxy : BaseProxy, IClientProxy
 	{
 		public ClientProxy(string address, ILogger logger) : base(address, logger)

SafeExamBrowser.Core/Communication/RuntimeProxy.cs

@@ -15,6 +15,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Communication
 {
+	/// <summary>
+	/// Default implementation of the <see cref="IRuntimeProxy"/>, to be used for communication with the runtime application component.
+	/// </summary>
 	public class RuntimeProxy : BaseProxy, IRuntimeProxy
 	{
 		public RuntimeProxy(string address, ILogger logger) : base(address, logger)

SafeExamBrowser.Core/Communication/ServiceProxy.cs

@@ -13,6 +13,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Communication
 {
+	/// <summary>
+	/// Default implementation of the <see cref="IServiceProxy"/>, to be used for communication with the service application component.
+	/// </summary>
 	public class ServiceProxy : BaseProxy, IServiceProxy
 	{
 		public bool Ignore { private get; set; }

SafeExamBrowser.Core/I18n/Text.cs

@@ -13,6 +13,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.I18n
 {
+	/// <summary>
+	/// Default implementation of the <see cref="IText"/> module.
+	/// </summary>
 	public class Text : IText
 	{
 		private IDictionary<TextKey, string> cache = new Dictionary<TextKey, string>();

SafeExamBrowser.Core/I18n/XmlTextResource.cs

@@ -14,6 +14,9 @@ using SafeExamBrowser.Contracts.I18n;
 
 namespace SafeExamBrowser.Core.I18n
 {
+	/// <summary>
+	/// Default implementation of <see cref="ITextResource"/> to load text data from XML files.
+	/// </summary>
 	public class XmlTextResource : ITextResource
 	{
 		private string path;
@@ -21,8 +24,8 @@ namespace SafeExamBrowser.Core.I18n
 		/// <summary>
 		/// Initializes a new text resource for an XML file located at the specified path.
 		/// </summary>
-		/// <exception cref="System.ArgumentException">If the specifed file does not exist.</exception>
-		/// <exception cref="System.ArgumentNullException">If the given path is null.</exception>
+		/// <exception cref="ArgumentException">If the specifed file does not exist.</exception>
+		/// <exception cref="ArgumentNullException">If the given path is null.</exception>
 		public XmlTextResource(string path)
 		{
 			if (path == null)

SafeExamBrowser.Core/Logging/DefaultLogFormatter.cs

@@ -11,6 +11,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Logging
 {
+	/// <summary>
+	/// Default implementation of <see cref="ILogContentFormatter"/>.
+	/// </summary>
 	public class DefaultLogFormatter : ILogContentFormatter
 	{
 		public string Format(ILogContent content)

SafeExamBrowser.Core/Logging/LogFileWriter.cs

@@ -12,6 +12,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Logging
 {
+	/// <summary>
+	/// <see cref="ILogObserver"/> which immediately saves new log content to disk.
+	/// </summary>
 	public class LogFileWriter : ILogObserver
 	{
 		private static readonly object @lock = new object();

SafeExamBrowser.Core/Logging/LogMessage.cs

@@ -11,6 +11,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Logging
 {
+	/// <summary>
+	/// Default implementation of <see cref="ILogMessage"/>.
+	/// </summary>
 	public class LogMessage : ILogMessage
 	{
 		public DateTime DateTime { get; private set; }

SafeExamBrowser.Core/Logging/LogText.cs

@@ -10,6 +10,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Logging
 {
+	/// <summary>
+	/// Default implementation of <see cref="ILogText"/>.
+	/// </summary>
 	public class LogText : ILogText
 	{
 		public string Text { get; private set; }

SafeExamBrowser.Core/Logging/Logger.cs

@@ -15,6 +15,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Logging
 {
+	/// <summary>
+	/// Default, thread-safe implementation of <see cref="ILogger"/>.
+	/// </summary>
 	public class Logger : ILogger
 	{
 		private static readonly object @lock = new object();

SafeExamBrowser.Core/Logging/ModuleLogger.cs

@@ -12,15 +12,14 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Logging
 {
+	/// <summary>
+	/// Wraps an implementation of <see cref="ILogger"/> in order to append information about the module from which messages are logged.
+	/// </summary>
 	public class ModuleLogger : ILogger
 	{
 		private ILogger logger;
 		private Type module;
 
-		/// <summary>
-		/// Creates a wrapper around an <c>ILogger</c> that includes information
-		/// about the specified module when logging messages with a severity.
-		/// </summary>
 		public ModuleLogger(ILogger logger, Type module)
 		{
 			this.logger = logger;

SafeExamBrowser.Core/Logging/ThreadInfo.cs

@@ -11,6 +11,9 @@ using SafeExamBrowser.Contracts.Logging;
 
 namespace SafeExamBrowser.Core.Logging
 {
+	/// <summary>
+	/// Default implementation of <see cref="IThreadInfo"/>.
+	/// </summary>
 	public class ThreadInfo : IThreadInfo
 	{
 		public int Id { get; private set; }