From a9306754d014e14b53bafa4344eb24f2ec7c6ebf Mon Sep 17 00:00:00 2001 From: dbuechel Date: Tue, 6 Mar 2018 14:35:10 +0100 Subject: [PATCH] SEBWIN-219: Documented types of core library. --- .../OperationModel/IOperationSequence.cs | 22 ++++++++++--------- .../Communication/ICommunicationHost.cs | 3 ++- .../Communication/ICommunicationProxy.cs | 3 ++- .../Operations/CommunicationOperation.cs | 4 ++++ .../DelayedInitializationOperation.cs | 5 +++++ .../Behaviour/Operations/DelegateOperation.cs | 4 ++++ .../Behaviour/Operations/I18nOperation.cs | 3 +++ .../Behaviour/Operations/OperationSequence.cs | 3 +++ .../Communication/BaseHost.cs | 3 +++ .../Communication/BaseProxy.cs | 4 ++++ .../Communication/ClientProxy.cs | 3 +++ .../Communication/RuntimeProxy.cs | 3 +++ .../Communication/ServiceProxy.cs | 3 +++ SafeExamBrowser.Core/I18n/Text.cs | 3 +++ SafeExamBrowser.Core/I18n/XmlTextResource.cs | 7 ++++-- .../Logging/DefaultLogFormatter.cs | 3 +++ SafeExamBrowser.Core/Logging/LogFileWriter.cs | 3 +++ SafeExamBrowser.Core/Logging/LogMessage.cs | 3 +++ SafeExamBrowser.Core/Logging/LogText.cs | 3 +++ SafeExamBrowser.Core/Logging/Logger.cs | 3 +++ SafeExamBrowser.Core/Logging/ModuleLogger.cs | 7 +++--- SafeExamBrowser.Core/Logging/ThreadInfo.cs | 3 +++ 22 files changed, 80 insertions(+), 18 deletions(-) diff --git a/SafeExamBrowser.Contracts/Behaviour/OperationModel/IOperationSequence.cs b/SafeExamBrowser.Contracts/Behaviour/OperationModel/IOperationSequence.cs index 16810312..fc90baf5 100644 --- a/SafeExamBrowser.Contracts/Behaviour/OperationModel/IOperationSequence.cs +++ b/SafeExamBrowser.Contracts/Behaviour/OperationModel/IOperationSequence.cs @@ -11,15 +11,15 @@ using SafeExamBrowser.Contracts.UserInterface; namespace SafeExamBrowser.Contracts.Behaviour.OperationModel { /// - /// A sequence of s which can be used for sequential procedures, e.g. the initialization & 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 s which can be used for sequential procedures, e.g. the initialization & 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: /// - /// : The operations will be performed according to their initialized order (A -> B -> C -> D). - /// : The operations will be repeated according to their initialized order (A -> B -> C -> D). - /// : The operations will be reverted according to the reversed initial order (D -> C -> B -> A). + /// : A -> B -> C -> D. + /// : A -> B -> C -> D. + /// : D -> C -> B -> A. /// public interface IOperationSequence { @@ -29,18 +29,20 @@ namespace SafeExamBrowser.Contracts.Behaviour.OperationModel IProgressIndicator ProgressIndicator { set; } /// - /// 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. /// OperationResult TryPerform(); /// - /// 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. /// OperationResult TryRepeat(); /// /// Tries to revert the operations of this sequence. Returns true if all operations were reverted without errors, - /// otherwise false. + /// otherwise false. The reversion of all operations will continue, even if one or multiple operations fail. /// bool TryRevert(); } diff --git a/SafeExamBrowser.Contracts/Communication/ICommunicationHost.cs b/SafeExamBrowser.Contracts/Communication/ICommunicationHost.cs index 2393248f..2b116de7 100644 --- a/SafeExamBrowser.Contracts/Communication/ICommunicationHost.cs +++ b/SafeExamBrowser.Contracts/Communication/ICommunicationHost.cs @@ -11,7 +11,8 @@ namespace SafeExamBrowser.Contracts.Communication public delegate void CommunicationEventHandler(); /// - /// 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). /// public interface ICommunicationHost { diff --git a/SafeExamBrowser.Contracts/Communication/ICommunicationProxy.cs b/SafeExamBrowser.Contracts/Communication/ICommunicationProxy.cs index ceab8a46..2fd4d08c 100644 --- a/SafeExamBrowser.Contracts/Communication/ICommunicationProxy.cs +++ b/SafeExamBrowser.Contracts/Communication/ICommunicationProxy.cs @@ -11,7 +11,8 @@ using System; namespace SafeExamBrowser.Contracts.Communication { /// - /// 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 of another application component. /// public interface ICommunicationProxy { diff --git a/SafeExamBrowser.Core/Behaviour/Operations/CommunicationOperation.cs b/SafeExamBrowser.Core/Behaviour/Operations/CommunicationOperation.cs index 74603973..5300c801 100644 --- a/SafeExamBrowser.Core/Behaviour/Operations/CommunicationOperation.cs +++ b/SafeExamBrowser.Core/Behaviour/Operations/CommunicationOperation.cs @@ -14,6 +14,10 @@ using SafeExamBrowser.Contracts.UserInterface; namespace SafeExamBrowser.Core.Behaviour.Operations { + /// + /// An operation to handle the lifetime of an . The host is started during , + /// stopped and restarted during (if not running) and stopped during . + /// public class CommunicationOperation : IOperation { private ICommunicationHost host; diff --git a/SafeExamBrowser.Core/Behaviour/Operations/DelayedInitializationOperation.cs b/SafeExamBrowser.Core/Behaviour/Operations/DelayedInitializationOperation.cs index 8a1f7405..d2099a0e 100644 --- a/SafeExamBrowser.Core/Behaviour/Operations/DelayedInitializationOperation.cs +++ b/SafeExamBrowser.Core/Behaviour/Operations/DelayedInitializationOperation.cs @@ -12,6 +12,11 @@ using SafeExamBrowser.Contracts.UserInterface; namespace SafeExamBrowser.Core.Behaviour.Operations { + /// + /// 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 has finished. + /// public class DelayedInitializationOperation : IOperation { private Func initialize; diff --git a/SafeExamBrowser.Core/Behaviour/Operations/DelegateOperation.cs b/SafeExamBrowser.Core/Behaviour/Operations/DelegateOperation.cs index 63b20c3d..6bb0a61c 100644 --- a/SafeExamBrowser.Core/Behaviour/Operations/DelegateOperation.cs +++ b/SafeExamBrowser.Core/Behaviour/Operations/DelegateOperation.cs @@ -12,6 +12,10 @@ using SafeExamBrowser.Contracts.UserInterface; namespace SafeExamBrowser.Core.Behaviour.Operations { + /// + /// A generic operation to allow for the (inline) definition of an operation via delegates. Useful if implementing a complete + /// would be an unnecessary overhead. + /// public class DelegateOperation : IOperation { private Action perform; diff --git a/SafeExamBrowser.Core/Behaviour/Operations/I18nOperation.cs b/SafeExamBrowser.Core/Behaviour/Operations/I18nOperation.cs index df710010..01d4e577 100644 --- a/SafeExamBrowser.Core/Behaviour/Operations/I18nOperation.cs +++ b/SafeExamBrowser.Core/Behaviour/Operations/I18nOperation.cs @@ -17,6 +17,9 @@ using SafeExamBrowser.Core.I18n; namespace SafeExamBrowser.Core.Behaviour.Operations { + /// + /// An operation to handle the initialization of an module with text data from the default directory. + /// public class I18nOperation : IOperation { private ILogger logger; diff --git a/SafeExamBrowser.Core/Behaviour/Operations/OperationSequence.cs b/SafeExamBrowser.Core/Behaviour/Operations/OperationSequence.cs index 345a333c..29fa91fc 100644 --- a/SafeExamBrowser.Core/Behaviour/Operations/OperationSequence.cs +++ b/SafeExamBrowser.Core/Behaviour/Operations/OperationSequence.cs @@ -15,6 +15,9 @@ using SafeExamBrowser.Contracts.UserInterface; namespace SafeExamBrowser.Core.Behaviour.Operations { + /// + /// Default implementation of the . + /// public class OperationSequence : IOperationSequence { private ILogger logger; diff --git a/SafeExamBrowser.Core/Communication/BaseHost.cs b/SafeExamBrowser.Core/Communication/BaseHost.cs index 02fffde0..8feb1ecd 100644 --- a/SafeExamBrowser.Core/Communication/BaseHost.cs +++ b/SafeExamBrowser.Core/Communication/BaseHost.cs @@ -16,6 +16,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Communication { + /// + /// The base implementation of an . Runs the host on a new, separate thread. + /// [ServiceBehavior(InstanceContextMode = InstanceContextMode.Single, ConcurrencyMode = ConcurrencyMode.Single)] public abstract class BaseHost : ICommunication, ICommunicationHost { diff --git a/SafeExamBrowser.Core/Communication/BaseProxy.cs b/SafeExamBrowser.Core/Communication/BaseProxy.cs index 321716a5..8484b6d3 100644 --- a/SafeExamBrowser.Core/Communication/BaseProxy.cs +++ b/SafeExamBrowser.Core/Communication/BaseProxy.cs @@ -16,6 +16,10 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Communication { + /// + /// Base implementation of an . Automatically starts a ping mechanism with a timeout of + /// once a connection was established. + /// public abstract class BaseProxy : ICommunicationProxy { private const int ONE_MINUTE = 60000; diff --git a/SafeExamBrowser.Core/Communication/ClientProxy.cs b/SafeExamBrowser.Core/Communication/ClientProxy.cs index f10978bc..996e4e8c 100644 --- a/SafeExamBrowser.Core/Communication/ClientProxy.cs +++ b/SafeExamBrowser.Core/Communication/ClientProxy.cs @@ -14,6 +14,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Communication { + /// + /// Default implementation of the , to be used for communication with the client application component. + /// public class ClientProxy : BaseProxy, IClientProxy { public ClientProxy(string address, ILogger logger) : base(address, logger) diff --git a/SafeExamBrowser.Core/Communication/RuntimeProxy.cs b/SafeExamBrowser.Core/Communication/RuntimeProxy.cs index ef0860f3..fb1cfe9f 100644 --- a/SafeExamBrowser.Core/Communication/RuntimeProxy.cs +++ b/SafeExamBrowser.Core/Communication/RuntimeProxy.cs @@ -15,6 +15,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Communication { + /// + /// Default implementation of the , to be used for communication with the runtime application component. + /// public class RuntimeProxy : BaseProxy, IRuntimeProxy { public RuntimeProxy(string address, ILogger logger) : base(address, logger) diff --git a/SafeExamBrowser.Core/Communication/ServiceProxy.cs b/SafeExamBrowser.Core/Communication/ServiceProxy.cs index 4fae2426..f44d7a1f 100644 --- a/SafeExamBrowser.Core/Communication/ServiceProxy.cs +++ b/SafeExamBrowser.Core/Communication/ServiceProxy.cs @@ -13,6 +13,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Communication { + /// + /// Default implementation of the , to be used for communication with the service application component. + /// public class ServiceProxy : BaseProxy, IServiceProxy { public bool Ignore { private get; set; } diff --git a/SafeExamBrowser.Core/I18n/Text.cs b/SafeExamBrowser.Core/I18n/Text.cs index 74ef9692..be3225f1 100644 --- a/SafeExamBrowser.Core/I18n/Text.cs +++ b/SafeExamBrowser.Core/I18n/Text.cs @@ -13,6 +13,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.I18n { + /// + /// Default implementation of the module. + /// public class Text : IText { private IDictionary cache = new Dictionary(); diff --git a/SafeExamBrowser.Core/I18n/XmlTextResource.cs b/SafeExamBrowser.Core/I18n/XmlTextResource.cs index 3586e2d5..769ff62f 100644 --- a/SafeExamBrowser.Core/I18n/XmlTextResource.cs +++ b/SafeExamBrowser.Core/I18n/XmlTextResource.cs @@ -14,6 +14,9 @@ using SafeExamBrowser.Contracts.I18n; namespace SafeExamBrowser.Core.I18n { + /// + /// Default implementation of to load text data from XML files. + /// public class XmlTextResource : ITextResource { private string path; @@ -21,8 +24,8 @@ namespace SafeExamBrowser.Core.I18n /// /// Initializes a new text resource for an XML file located at the specified path. /// - /// If the specifed file does not exist. - /// If the given path is null. + /// If the specifed file does not exist. + /// If the given path is null. public XmlTextResource(string path) { if (path == null) diff --git a/SafeExamBrowser.Core/Logging/DefaultLogFormatter.cs b/SafeExamBrowser.Core/Logging/DefaultLogFormatter.cs index 2b88ec2d..ece3f9e8 100644 --- a/SafeExamBrowser.Core/Logging/DefaultLogFormatter.cs +++ b/SafeExamBrowser.Core/Logging/DefaultLogFormatter.cs @@ -11,6 +11,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Logging { + /// + /// Default implementation of . + /// public class DefaultLogFormatter : ILogContentFormatter { public string Format(ILogContent content) diff --git a/SafeExamBrowser.Core/Logging/LogFileWriter.cs b/SafeExamBrowser.Core/Logging/LogFileWriter.cs index fe72ba9b..5d932be8 100644 --- a/SafeExamBrowser.Core/Logging/LogFileWriter.cs +++ b/SafeExamBrowser.Core/Logging/LogFileWriter.cs @@ -12,6 +12,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Logging { + /// + /// which immediately saves new log content to disk. + /// public class LogFileWriter : ILogObserver { private static readonly object @lock = new object(); diff --git a/SafeExamBrowser.Core/Logging/LogMessage.cs b/SafeExamBrowser.Core/Logging/LogMessage.cs index 2a3508b0..6a323164 100644 --- a/SafeExamBrowser.Core/Logging/LogMessage.cs +++ b/SafeExamBrowser.Core/Logging/LogMessage.cs @@ -11,6 +11,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Logging { + /// + /// Default implementation of . + /// public class LogMessage : ILogMessage { public DateTime DateTime { get; private set; } diff --git a/SafeExamBrowser.Core/Logging/LogText.cs b/SafeExamBrowser.Core/Logging/LogText.cs index 9edf1ec0..a7c04412 100644 --- a/SafeExamBrowser.Core/Logging/LogText.cs +++ b/SafeExamBrowser.Core/Logging/LogText.cs @@ -10,6 +10,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Logging { + /// + /// Default implementation of . + /// public class LogText : ILogText { public string Text { get; private set; } diff --git a/SafeExamBrowser.Core/Logging/Logger.cs b/SafeExamBrowser.Core/Logging/Logger.cs index 34ab4d5f..15c316ab 100644 --- a/SafeExamBrowser.Core/Logging/Logger.cs +++ b/SafeExamBrowser.Core/Logging/Logger.cs @@ -15,6 +15,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Logging { + /// + /// Default, thread-safe implementation of . + /// public class Logger : ILogger { private static readonly object @lock = new object(); diff --git a/SafeExamBrowser.Core/Logging/ModuleLogger.cs b/SafeExamBrowser.Core/Logging/ModuleLogger.cs index 7370cf7c..b48a2d70 100644 --- a/SafeExamBrowser.Core/Logging/ModuleLogger.cs +++ b/SafeExamBrowser.Core/Logging/ModuleLogger.cs @@ -12,15 +12,14 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Logging { + /// + /// Wraps an implementation of in order to append information about the module from which messages are logged. + /// public class ModuleLogger : ILogger { private ILogger logger; private Type module; - /// - /// Creates a wrapper around an ILogger that includes information - /// about the specified module when logging messages with a severity. - /// public ModuleLogger(ILogger logger, Type module) { this.logger = logger; diff --git a/SafeExamBrowser.Core/Logging/ThreadInfo.cs b/SafeExamBrowser.Core/Logging/ThreadInfo.cs index 9921411f..2f3baa1b 100644 --- a/SafeExamBrowser.Core/Logging/ThreadInfo.cs +++ b/SafeExamBrowser.Core/Logging/ThreadInfo.cs @@ -11,6 +11,9 @@ using SafeExamBrowser.Contracts.Logging; namespace SafeExamBrowser.Core.Logging { + /// + /// Default implementation of . + /// public class ThreadInfo : IThreadInfo { public int Id { get; private set; }