From e30dffc419410a5c9021cfd015544990be5dbb81 Mon Sep 17 00:00:00 2001 From: Ben Olden-Cooligan Date: Wed, 29 Aug 2018 15:34:49 -0400 Subject: [PATCH] Comment all classes WIP --- NAPS2.Core/Scan/IScanDriver.cs | 2 +- NAPS2.Core/Scan/IScanDriverFactory.cs | 3 ++ NAPS2.Core/Scan/IScanPerformer.cs | 4 ++ NAPS2.Core/Scan/KeyValueScanOptions.cs | 6 +++ .../Scan/LocalizedDescriptionAttribute.cs | 4 ++ NAPS2.Core/Scan/OldScanSettings.cs | 6 +++ NAPS2.Core/Scan/PatchCode.cs | 4 ++ NAPS2.Core/Scan/PatchCodeDetector.cs | 4 ++ NAPS2.Core/Scan/ProfileNameTracker.cs | 5 +++ NAPS2.Core/Scan/ScanDevice.cs | 3 ++ NAPS2.Core/Scan/ScanDriverBase.cs | 3 ++ NAPS2.Core/Scan/ScanParams.cs | 4 ++ NAPS2.Core/Scan/ScanPerformer.cs | 4 ++ NAPS2.Core/Scan/ScanProfile.cs | 42 +++++++++++++++++++ NAPS2.Core/Util/Win32Window.cs | 3 ++ NAPS2.Core/Worker/BackgroundForm.cs | 4 ++ NAPS2.Core/Worker/IWorkerService.cs | 4 +- NAPS2.Core/Worker/IWorkerServiceFactory.cs | 3 ++ NAPS2.Core/Worker/ProcessJob.cs | 5 +++ NAPS2.Core/Worker/WorkerContext.cs | 3 ++ NAPS2.Core/Worker/WorkerManager.cs | 3 ++ NAPS2.Core/Worker/WorkerService.cs | 5 ++- 22 files changed, 120 insertions(+), 4 deletions(-) diff --git a/NAPS2.Core/Scan/IScanDriver.cs b/NAPS2.Core/Scan/IScanDriver.cs index 9cea86699..00fe53c07 100644 --- a/NAPS2.Core/Scan/IScanDriver.cs +++ b/NAPS2.Core/Scan/IScanDriver.cs @@ -8,7 +8,7 @@ using NAPS2.Scan.Images; namespace NAPS2.Scan { /// - /// An interface for document scanning drivers (e.g. WIA, TWAIN). + /// An interface for document scanning drivers (WIA, TWAIN, SANE). /// public interface IScanDriver { diff --git a/NAPS2.Core/Scan/IScanDriverFactory.cs b/NAPS2.Core/Scan/IScanDriverFactory.cs index 1bc32a028..f79dc4063 100644 --- a/NAPS2.Core/Scan/IScanDriverFactory.cs +++ b/NAPS2.Core/Scan/IScanDriverFactory.cs @@ -4,6 +4,9 @@ using System.Linq; namespace NAPS2.Scan { + /// + /// An interface used to create instances of IScanDriver based on the driver name. + /// public interface IScanDriverFactory { IScanDriver Create(string driverName); diff --git a/NAPS2.Core/Scan/IScanPerformer.cs b/NAPS2.Core/Scan/IScanPerformer.cs index 4e4f58406..ec747b33b 100644 --- a/NAPS2.Core/Scan/IScanPerformer.cs +++ b/NAPS2.Core/Scan/IScanPerformer.cs @@ -8,6 +8,10 @@ using NAPS2.Util; namespace NAPS2.Scan { + /// + /// A high-level interface used for scanning. + /// This abstracts away the logic of obtaining and using an instance of IScanDriver. + /// public interface IScanPerformer { Task PerformScan(ScanProfile scanProfile, ScanParams scanParams, IWin32Window dialogParent, ISaveNotify notify, Action imageCallback); diff --git a/NAPS2.Core/Scan/KeyValueScanOptions.cs b/NAPS2.Core/Scan/KeyValueScanOptions.cs index 6eb4cdbdd..7c97a556a 100644 --- a/NAPS2.Core/Scan/KeyValueScanOptions.cs +++ b/NAPS2.Core/Scan/KeyValueScanOptions.cs @@ -7,6 +7,12 @@ using System.Xml.Serialization; namespace NAPS2.Scan { + /// + /// A set of key-value options used for scanning. + /// + /// This is only relevant for SANE. Currently NAPS2 does not actually support viewing/setting custom options. + /// If someone was so inclined they could manually set them in the profiles.xml file. + /// public class KeyValueScanOptions : Dictionary, IXmlSerializable { public KeyValueScanOptions() diff --git a/NAPS2.Core/Scan/LocalizedDescriptionAttribute.cs b/NAPS2.Core/Scan/LocalizedDescriptionAttribute.cs index 8445c5943..6b45e45d6 100644 --- a/NAPS2.Core/Scan/LocalizedDescriptionAttribute.cs +++ b/NAPS2.Core/Scan/LocalizedDescriptionAttribute.cs @@ -6,6 +6,10 @@ using System.Resources; namespace NAPS2.Scan { + /// + /// An attribute used for enum values that assigns a string from a resources file. + /// The string value is accessed using the ScanEnumExtensions.Description extension method. + /// public class LocalizedDescriptionAttribute : DescriptionAttribute { private readonly string resourceName; diff --git a/NAPS2.Core/Scan/OldScanSettings.cs b/NAPS2.Core/Scan/OldScanSettings.cs index fdb4761f0..177b52605 100644 --- a/NAPS2.Core/Scan/OldScanSettings.cs +++ b/NAPS2.Core/Scan/OldScanSettings.cs @@ -5,6 +5,9 @@ using System.Xml.Serialization; namespace NAPS2.Scan { + /// + /// Used for compatibility when reading old profiles.xml files. + /// [XmlInclude(typeof(OldExtendedScanSettings))] [XmlType("ScanSettings")] public class OldScanSettings @@ -22,6 +25,9 @@ namespace NAPS2.Scan public bool IsDefault { get; set; } } + /// + /// Used for compatibility when reading old profiles.xml files. + /// [XmlType("ExtendedScanSettings")] public class OldExtendedScanSettings : OldScanSettings { diff --git a/NAPS2.Core/Scan/PatchCode.cs b/NAPS2.Core/Scan/PatchCode.cs index 7beaa3b82..bd6a1e2d6 100644 --- a/NAPS2.Core/Scan/PatchCode.cs +++ b/NAPS2.Core/Scan/PatchCode.cs @@ -4,6 +4,10 @@ using System.Linq; namespace NAPS2.Scan { + /// + /// A representation for which patch code, if any, has been detected on a document. + /// http://www.alliancegroup.co.uk/patch-codes.htm + /// public enum PatchCode { None, diff --git a/NAPS2.Core/Scan/PatchCodeDetector.cs b/NAPS2.Core/Scan/PatchCodeDetector.cs index 244eac754..b57f4ee72 100644 --- a/NAPS2.Core/Scan/PatchCodeDetector.cs +++ b/NAPS2.Core/Scan/PatchCodeDetector.cs @@ -6,6 +6,10 @@ using ZXing; namespace NAPS2.Scan { + /// + /// A wrapper around the ZXing library that detects patch codes. + /// http://www.alliancegroup.co.uk/patch-codes.htm + /// public class PatchCodeDetector { public static PatchCode Detect(Bitmap bitmap) diff --git a/NAPS2.Core/Scan/ProfileNameTracker.cs b/NAPS2.Core/Scan/ProfileNameTracker.cs index 721aefb73..59a38deaf 100644 --- a/NAPS2.Core/Scan/ProfileNameTracker.cs +++ b/NAPS2.Core/Scan/ProfileNameTracker.cs @@ -5,6 +5,11 @@ using NAPS2.Config; namespace NAPS2.Scan { + /// + /// A class used to help keep profile names consistent across forms. + /// + /// TODO: This should probably be replaced by an event handler system. + /// public class ProfileNameTracker { private readonly IUserConfigManager userConfigManager; diff --git a/NAPS2.Core/Scan/ScanDevice.cs b/NAPS2.Core/Scan/ScanDevice.cs index 4ebb1b8e9..761b377b6 100644 --- a/NAPS2.Core/Scan/ScanDevice.cs +++ b/NAPS2.Core/Scan/ScanDevice.cs @@ -4,6 +4,9 @@ using System.Linq; namespace NAPS2.Scan { + /// + /// The representation of a scanning device identified by a driver. + /// [Serializable] public class ScanDevice { diff --git a/NAPS2.Core/Scan/ScanDriverBase.cs b/NAPS2.Core/Scan/ScanDriverBase.cs index c83643ac1..e4c081897 100644 --- a/NAPS2.Core/Scan/ScanDriverBase.cs +++ b/NAPS2.Core/Scan/ScanDriverBase.cs @@ -7,6 +7,9 @@ using NAPS2.Scan.Images; namespace NAPS2.Scan { + /// + /// A base class for IScanDriver implementing common error handling. + /// public abstract class ScanDriverBase : IScanDriver { public abstract string DriverName { get; } diff --git a/NAPS2.Core/Scan/ScanParams.cs b/NAPS2.Core/Scan/ScanParams.cs index 6cecec7f2..6a04118ee 100644 --- a/NAPS2.Core/Scan/ScanParams.cs +++ b/NAPS2.Core/Scan/ScanParams.cs @@ -4,6 +4,10 @@ using System.Linq; namespace NAPS2.Scan { + /// + /// Scan configuration that is separate from the user profile. + /// This lets scans behave a bit differently in the Batch Scan window, NAPS2.Console, etc. + /// public class ScanParams { public bool DetectPatchCodes { get; set; } diff --git a/NAPS2.Core/Scan/ScanPerformer.cs b/NAPS2.Core/Scan/ScanPerformer.cs index f99000c87..50cc1fd92 100644 --- a/NAPS2.Core/Scan/ScanPerformer.cs +++ b/NAPS2.Core/Scan/ScanPerformer.cs @@ -11,6 +11,10 @@ using NAPS2.Util; namespace NAPS2.Scan { + /// + /// A high-level interface used for scanning. + /// This abstracts away the logic of obtaining and using an instance of IScanDriver. + /// public class ScanPerformer : IScanPerformer { private readonly IScanDriverFactory driverFactory; diff --git a/NAPS2.Core/Scan/ScanProfile.cs b/NAPS2.Core/Scan/ScanProfile.cs index 9feb8d6fb..8c7226060 100644 --- a/NAPS2.Core/Scan/ScanProfile.cs +++ b/NAPS2.Core/Scan/ScanProfile.cs @@ -9,6 +9,9 @@ using NAPS2.Lang.Resources; namespace NAPS2.Scan { + /// + /// A class that stores user configuration for scanning, including device selection and other options. + /// [Serializable] public class ScanProfile { @@ -115,6 +118,9 @@ namespace NAPS2.Scan public KeyValueScanOptions KeyValueOptions { get; set; } } + /// + /// User configuration for the Auto Save feature, which saves to a file immediately after scanning. + /// [Serializable] public class AutoSaveSettings { @@ -134,6 +140,9 @@ namespace NAPS2.Scan public SaveSeparator Separator { get; set; } } + /// + /// The type of TWAIN driver implementation (this option is provided for compatibility). + /// public enum TwainImpl { [LocalizedDescription(typeof(SettingsResources), "TwainImpl_Default")] @@ -148,6 +157,9 @@ namespace NAPS2.Scan X64 } + /// + /// The physical source of the scanned image (flatbed, feeder). + /// public enum ScanSource { [LocalizedDescription(typeof(SettingsResources), "Source_Glass")] @@ -158,6 +170,9 @@ namespace NAPS2.Scan Duplex } + /// + /// The color depth used for scanning. + /// public enum ScanBitDepth { [LocalizedDescription(typeof(SettingsResources), "BitDepth_24Color")] @@ -168,6 +183,9 @@ namespace NAPS2.Scan BlackWhite } + /// + /// The resolution used for scanning. + /// public enum ScanDpi { [LocalizedDescription(typeof(SettingsResources), "Dpi_100")] @@ -188,6 +206,9 @@ namespace NAPS2.Scan Dpi1200 } + /// + /// The physical location of the page relative to the scan area. + /// public enum ScanHorizontalAlign { [LocalizedDescription(typeof(SettingsResources), "HorizontalAlign_Left")] @@ -198,6 +219,9 @@ namespace NAPS2.Scan Right } + /// + /// A scale factor used to shrink the scanned image. + /// public enum ScanScale { [LocalizedDescription(typeof(SettingsResources), "Scale_1_1")] @@ -210,6 +234,9 @@ namespace NAPS2.Scan OneToEight } + /// + /// The page size used for scanning. + /// public enum ScanPageSize { [LocalizedDescription(typeof(SettingsResources), "PageSize_Letter")] @@ -237,6 +264,9 @@ namespace NAPS2.Scan Custom } + /// + /// Configuration for a particular page size. + /// [Serializable] public class PageDimensions { @@ -272,6 +302,9 @@ namespace NAPS2.Scan public static bool operator !=(PageDimensions x, PageDimensions y) => !(x == y); } + /// + /// Configuration for a user-created custom page size. + /// public class NamedPageSize { public string Name { get; set; } @@ -279,6 +312,9 @@ namespace NAPS2.Scan public PageDimensions Dimens { get; set; } } + /// + /// Helper attribute used to assign physical dimensions to the ScanPageSize enum. + /// public class PageDimensionsAttribute : Attribute { public PageDimensionsAttribute(string width, string height, PageSizeUnit unit) @@ -294,6 +330,9 @@ namespace NAPS2.Scan public PageDimensions PageDimensions { get; } } + /// + /// The unit used for Width and Height in PageDimensions. + /// public enum PageSizeUnit { [LocalizedDescription(typeof(SettingsResources), "PageSizeUnit_Inch")] @@ -304,6 +343,9 @@ namespace NAPS2.Scan Millimetre } + /// + /// Helper extensions that get additional information from scan-related objects and enumerations. + /// public static class ScanEnumExtensions { public static decimal WidthInMm(this PageDimensions pageDimensions) diff --git a/NAPS2.Core/Util/Win32Window.cs b/NAPS2.Core/Util/Win32Window.cs index aeaa3f04c..d477c6b22 100644 --- a/NAPS2.Core/Util/Win32Window.cs +++ b/NAPS2.Core/Util/Win32Window.cs @@ -5,6 +5,9 @@ using System.Windows.Forms; namespace NAPS2.Util { + /// + /// A trivial implementation of IWin32Window for use when serializing window handles cross-process. + /// public class Win32Window : IWin32Window { public Win32Window(IntPtr hwnd) diff --git a/NAPS2.Core/Worker/BackgroundForm.cs b/NAPS2.Core/Worker/BackgroundForm.cs index eeb84591c..f9999ddca 100644 --- a/NAPS2.Core/Worker/BackgroundForm.cs +++ b/NAPS2.Core/Worker/BackgroundForm.cs @@ -5,6 +5,10 @@ using System.Windows.Forms; namespace NAPS2.Worker { + /// + /// A basic implementation of an invisible form used in NAPS2.Worker.exe as a parent + /// for any dialogs that may need to be displayed. + /// public class BackgroundForm : Form { public BackgroundForm() diff --git a/NAPS2.Core/Worker/IWorkerService.cs b/NAPS2.Core/Worker/IWorkerService.cs index 6d65b7b20..69c4ea0fb 100644 --- a/NAPS2.Core/Worker/IWorkerService.cs +++ b/NAPS2.Core/Worker/IWorkerService.cs @@ -2,12 +2,14 @@ using System.Collections.Generic; using System.Linq; using System.ServiceModel; -using NAPS2.Operation; using NAPS2.Recovery; using NAPS2.Scan; namespace NAPS2.Worker { + /// + /// The WCF service interface for NAPS2.Worker.exe. + /// [ServiceContract] public interface IWorkerService { diff --git a/NAPS2.Core/Worker/IWorkerServiceFactory.cs b/NAPS2.Core/Worker/IWorkerServiceFactory.cs index cced70a20..4580511fd 100644 --- a/NAPS2.Core/Worker/IWorkerServiceFactory.cs +++ b/NAPS2.Core/Worker/IWorkerServiceFactory.cs @@ -4,6 +4,9 @@ using System.Linq; namespace NAPS2.Worker { + /// + /// A factory interface to spawn NAPS2.Worker.exe instances as needed. + /// public interface IWorkerServiceFactory { WorkerContext Create(); diff --git a/NAPS2.Core/Worker/ProcessJob.cs b/NAPS2.Core/Worker/ProcessJob.cs index cad60249a..98a4cf9e7 100644 --- a/NAPS2.Core/Worker/ProcessJob.cs +++ b/NAPS2.Core/Worker/ProcessJob.cs @@ -6,6 +6,11 @@ using System.Runtime.InteropServices; namespace NAPS2.Worker { + /// + /// A helper class to provide access to Job Objects. This is used to group NAPS2.Worker.exe processes with + /// the calling executable, so that there are no zombie processes left behind if the caller terminates. + /// https://docs.microsoft.com/en-us/windows/desktop/procthread/job-objects + /// public class Job : IDisposable { [DllImport("kernel32.dll", CharSet = CharSet.Unicode)] diff --git a/NAPS2.Core/Worker/WorkerContext.cs b/NAPS2.Core/Worker/WorkerContext.cs index abdf22938..7c7972486 100644 --- a/NAPS2.Core/Worker/WorkerContext.cs +++ b/NAPS2.Core/Worker/WorkerContext.cs @@ -4,6 +4,9 @@ using System.Linq; namespace NAPS2.Worker { + /// + /// A class storing the objects the client needs to use a NAPS2.Worker.exe instance. + /// public class WorkerContext : IDisposable { public IWorkerService Service { get; set; } diff --git a/NAPS2.Core/Worker/WorkerManager.cs b/NAPS2.Core/Worker/WorkerManager.cs index e958c316e..f890993c8 100644 --- a/NAPS2.Core/Worker/WorkerManager.cs +++ b/NAPS2.Core/Worker/WorkerManager.cs @@ -11,6 +11,9 @@ using NAPS2.Platform; namespace NAPS2.Worker { + /// + /// A class to manage the lifecycle of NAPS2.Worker.exe instances and hook up the WCF channels. + /// public static class WorkerManager { public const string PIPE_NAME_FORMAT = "net.pipe://localhost/NAPS2.Worker/{0}"; diff --git a/NAPS2.Core/Worker/WorkerService.cs b/NAPS2.Core/Worker/WorkerService.cs index f057fb6f9..39cc8f2d7 100644 --- a/NAPS2.Core/Worker/WorkerService.cs +++ b/NAPS2.Core/Worker/WorkerService.cs @@ -4,8 +4,6 @@ using System.IO; using System.Linq; using System.ServiceModel; using System.Windows.Forms; -using NAPS2.ImportExport.Pdf; -using NAPS2.Operation; using NAPS2.Recovery; using NAPS2.Scan; using NAPS2.Scan.Twain; @@ -13,6 +11,9 @@ using NAPS2.Util; namespace NAPS2.Worker { + /// + /// The WCF service implementation for NAPS2.Worker.exe. + /// [ServiceBehavior(InstanceContextMode = InstanceContextMode.Single, IncludeExceptionDetailInFaults = true, ConcurrencyMode = ConcurrencyMode.Multiple)]