Comments for all classes WIP

NAPS2.Core/Operation/IOperation.cs

@@ -5,6 +5,9 @@ using System.Threading.Tasks;
 
 namespace NAPS2.Operation
 {
+    /// <summary>
+    /// A representation of a long-running operation with progress reporting and cancellation.
+    /// </summary>
     public interface IOperation
     {
         string ProgressTitle { get; }

NAPS2.Core/Operation/IOperationProgress.cs

@@ -4,6 +4,11 @@ using System.Linq;
 
 namespace NAPS2.Operation
 {
+    /// <summary>
+    /// A base interface for objects capabable of displaying progress for an operation.
+    ///
+    /// Implementors: WinFormsOperationProgress, ConsoleOperationProgress
+    /// </summary>
     public interface IOperationProgress
     {
         void ShowProgress(IOperation op);

NAPS2.Core/Operation/OperationBase.cs

@@ -4,6 +4,9 @@ using System.Linq;
 
 namespace NAPS2.Operation
 {
+    /// <summary>
+    /// A base implementation for IOperation, helping with common event logic.
+    /// </summary>
     public abstract class OperationBase : IOperation
     {
         protected volatile bool cancel;

NAPS2.Core/Operation/OperationErrorEventArgs.cs

@@ -4,6 +4,9 @@ using System.Linq;
 
 namespace NAPS2.Operation
 {
+    /// <summary>
+    /// Arguments for the IOperation.Error event.
+    /// </summary>
     public class OperationErrorEventArgs : EventArgs
     {
         public OperationErrorEventArgs(string errorMessage, Exception exception)

NAPS2.Core/Operation/OperationStatus.cs

@@ -4,6 +4,9 @@ using System.Linq;
 
 namespace NAPS2.Operation
 {
+    /// <summary>
+    /// A representation of the current status of an IOperation.
+    /// </summary>
     public class OperationStatus
     {
         public string StatusText { get; set; }

NAPS2.Core/Operation/WorkerOperation.cs

@@ -9,6 +9,9 @@ using NAPS2.Worker;
 
 namespace NAPS2.Operation
 {
+    /// <summary>
+    /// A base class for operations that can proxy part of the operation to a worker process.
+    /// </summary>
     public abstract class WorkerOperation : OperationBase
     {
         private readonly IWorkerServiceFactory workerServiceFactory;
@@ -18,10 +21,18 @@ namespace NAPS2.Operation
             this.workerServiceFactory = workerServiceFactory;
         }
 
+        /// <summary>
+        /// A value indicating whether DoWork should proxy to a worker process.
+        /// </summary>
         protected virtual bool UseWorker => true;
 
         public ProgressHandler ProgressProxy { get; set; }
 
+        /// <summary>
+        /// Calls DoWorkInternal either directly or through a proxy to a worker process, determined by the value of UseWorker.
+        /// </summary>
+        /// <param name="args">The arguments to be passed to DoWorkInternal.</param>
+        /// <returns>A value indicating whether the operation was successful.</returns>
         protected bool DoWork(WorkArgs args)
         {
             if (UseWorker)
@@ -45,6 +56,11 @@ namespace NAPS2.Operation
             return ProgressProxy?.Invoke(current, max) ?? base.OnProgress(current, max);
         }
 
+        /// <summary>
+        /// The base class for arguments passed to DoWork and consumed by DoWorkInternal.
+        ///
+        /// Subclasses must ensure that they are serializable by DataContractSerializer and will work as intended cross-process.
+        /// </summary>
         [KnownType("DerivedTypes")]
         [Serializable]
         public class WorkArgs

NAPS2.Core/Recovery/RecoveryImage.cs

@@ -73,7 +73,7 @@ namespace NAPS2.Recovery
         {
             if (_recoveryIndexManager != null)
             {
-                _recoveryIndexManager.Index.Images.RemoveAll();
+                _recoveryIndexManager.Index.Images.Clear();
                 _recoveryIndexManager.Index.Images.AddRange(images.Select(x => x.RecoveryIndexImage));
                 _recoveryIndexManager.Save();
             }

NAPS2.Core/Util/ChangeTracker.cs

@@ -4,6 +4,9 @@ using System.Linq;
 
 namespace NAPS2.Util
 {
+    /// <summary>
+    /// A singleton class used to track whether the user has made unsaved changes, and therefore should be prompted before exiting.
+    /// </summary>
     public class ChangeTracker
     {
         public bool HasUnsavedChanges { get; set; }

NAPS2.Core/Util/ChaosMonkey.cs

@@ -7,6 +7,9 @@ using System.Threading;
 
 namespace NAPS2.Util
 {
+    /// <summary>
+    /// A debug helper that randomly causes delays or errors.
+    /// </summary>
     internal static class ChaosMonkey
     {
         private static Lazy<Random> random = new Lazy<Random>();

NAPS2.Core/Util/CollectionExtensions.cs

@@ -7,14 +7,11 @@ namespace NAPS2.Util
 {
     public static class CollectionExtensions
     {
-        public static void RemoveAll(this IList list)
-        {
-            foreach (int i in Enumerable.Range(0, list.Count))
-            {
-                list.RemoveAt(0);
-            }
-        }
-
+        /// <summary>
+        /// Removes multiple elements from the list at the specified indices.
+        /// </summary>
+        /// <param name="list"></param>
+        /// <param name="indices"></param>
         public static void RemoveAll(this IList list, IEnumerable<int> indices)
         {
             int offset = 0;
@@ -24,11 +21,25 @@ namespace NAPS2.Util
             }
         }
 
+        /// <summary>
+        /// Gets an enumerable of elements at the specified indices.
+        /// </summary>
+        /// <typeparam name="T"></typeparam>
+        /// <param name="list"></param>
+        /// <param name="indices"></param>
+        /// <returns></returns>
         public static IEnumerable<T> ElementsAt<T>(this IList<T> list, IEnumerable<int> indices)
         {
             return indices.Select(i => list[i]);
         }
 
+        /// <summary>
+        /// Gets an enumerable of indices of the specified elements.
+        /// </summary>
+        /// <typeparam name="T"></typeparam>
+        /// <param name="list"></param>
+        /// <param name="elements"></param>
+        /// <returns></returns>
         public static IEnumerable<int> IndiciesOf<T>(this IList<T> list, IEnumerable<T> elements)
         {
             return elements.Select(list.IndexOf);

NAPS2.Core/Util/ConditionalControls.cs

@@ -7,6 +7,11 @@ using System.Windows.Forms;
 
 namespace NAPS2.Util
 {
+    /// <summary>
+    /// Helpers for conditionally visible controls that use simple heuristics help maintain the visual appearance of forms.
+    ///
+    /// For example, if a checkbox is hidden, the form will shrink and controls further down will be moved up to fill the empty space.
+    /// </summary>
     public static class ConditionalControls
     {
         public static void SetVisible(Control control, bool visible)

NAPS2.Core/Util/CultureInitializer.cs

@@ -7,6 +7,9 @@ using NAPS2.Config;
 
 namespace NAPS2.Util
 {
+    /// <summary>
+    /// A helper to set the thread culture based on user and app configuration.
+    /// </summary>
     public class CultureInitializer
     {
         private readonly IUserConfigManager userConfigManager;

NAPS2.Core/Util/ExceptionExtensions.cs

@@ -15,6 +15,11 @@ namespace NAPS2.Util
             internalPreserveStackTrace = typeof(Exception).GetMethod("InternalPreserveStackTrace", BindingFlags.Instance | BindingFlags.NonPublic);
         }
 
+        /// <summary>
+        /// Maintains the stack trace of an exception even after it is rethrown.
+        /// This can be helpful when marshalling exceptions across process boundaries.
+        /// </summary>
+        /// <param name="e"></param>
         public static void PreserveStackTrace(this Exception e)
         {
             if (internalPreserveStackTrace != null)

NAPS2.Core/Util/IErrorOutput.cs

@@ -4,6 +4,11 @@ using System.Linq;
 
 namespace NAPS2.Util
 {
+    /// <summary>
+    /// A base interface for objects capable of displaying error output.
+    ///
+    /// Implementors: MessageBoxErrorOutput, ConsoleErrorOutput
+    /// </summary>
     public interface IErrorOutput
     {
         void DisplayError(string errorMessage);

NAPS2.Core/Util/ILogger.cs

@@ -4,6 +4,9 @@ using System.Linq;
 
 namespace NAPS2.Util
 {
+    /// <summary>
+    /// A base interface for logging APIs.
+    /// </summary>
     public interface ILogger
     {
         void Error(string message);

NAPS2.Core/Util/IOverwritePrompt.cs

@@ -6,8 +6,20 @@ using System.Windows.Forms;
 
 namespace NAPS2.Util
 {
+    /// <summary>
+    /// A base interface for objects that can prompt the user to overwrite an existing file.
+    ///
+    /// Implementors: WinFormsOverwritePrompt, ConsoleOverwritePrompt
+    /// </summary>
     public interface IOverwritePrompt
     {
+        /// <summary>
+        /// Asks the user if they would like to overwrite the specified file.
+        ///
+        /// If DialogResult.Cancel is specified, the current operation should be cancelled even if there are other files to write.
+        /// </summary>
+        /// <param name="path">The path of the file to overwrite.</param>
+        /// <returns>Yes, No, or Cancel.</returns>
         DialogResult ConfirmOverwrite(string path);
     }
 }

NAPS2.Core/WinForms/FDesktop.cs

@@ -251,7 +251,7 @@ namespace NAPS2.WinForms
             // Update localized values
             // Since all forms are opened modally and this is the root form, it should be the only one that needs to be updated live
             SaveFormState = false;
-            Controls.RemoveAll();
+            Controls.Clear();
             UpdateRTL();
             InitializeComponent();
             PostInitializeComponent();