Added documentation to library

DisplaySettings/DisplaySettings.csproj

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <TargetFramework>netstandard2.0</TargetFramework>
     <Authors>biosmanager</Authors>
-    <Version>1.0.0</Version>
+    <Version>1.0.1</Version>
     <Description>Library to change or retrieve display information and settings.</Description>
     <Copyright>Copyright © 2020 biosmanager</Copyright>
     <PackageLicenseFile>LICENSE.md</PackageLicenseFile>
@@ -12,6 +12,12 @@
     <RepositoryType>git</RepositoryType>
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
+    <DocumentationFile>$(BaseOutputPath)\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
+  </PropertyGroup>
+
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
+    <DebugType>none</DebugType>
+    <DebugSymbols>false</DebugSymbols>
   </PropertyGroup>
 
   <ItemGroup>

DisplaySettings/Source/DisplayInformation.cs

@@ -7,44 +7,126 @@
 namespace DisplaySettings
 {
     /// <summary>
-    /// Contains information about about a display adapter and all its monitors
+    /// Contains information about about a display adapter and all its monitors.
     /// </summary>
     public sealed class DisplayInformation
     {
-        // Flags based on wingdi.h from Windows SDK 10.0.16299.0
+        /// <summary>
+        /// States of a of display adapter or monitor.
+        /// </summary>
+        /// <remarks>
+        /// Flags based on wingdi.h from Windows SDK 10.0.16299.0.
+        /// </remarks>
         [Flags]
         public enum DisplayDeviceStateFlags : uint
         {
+            /// <summary>
+            /// Device is currently attached to the desktop.
+            /// </summary>
             AttachedToDesktop = 0x00000001,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             MultiDriver = 0x00000002,
+            /// <summary>
+            /// Device is the primary device.
+            /// </summary>
             PrimaryDevice = 0x00000004,
+            /// <summary>
+            /// Device is mirroring another device.
+            /// </summary>
             MirroringDriver = 0x00000008,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             VgaCompatible = 0x00000010,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             Removable = 0x00000020,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             AccDriver = 0x00000040,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             ModesPruned = 0x08000000,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             RdpUdd = 0x01000000,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             Remote = 0x04000000,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             Disconnect = 0x02000000,
+            /// <summary>
+            /// Not documented.
+            /// </summary>
             TSCompatible = 0x00200000,
+            /// <summary>
+            /// Device has unsafe graphics modes enabled.
+            /// </summary>
             UnsafeModesOn = 0x00080000
         }
 
+        /// <summary>
+        /// Monitor device
+        /// </summary>
         public sealed class Monitor
         {
+            /// <summary>
+            /// Index on adapter. It can be -1 if the mode cannot be found in all available modes for a display.
+            /// </summary>
             public int MonitorIndex { get; set; }
+            /// <summary>
+            /// Path on adapter.
+            /// </summary>
             public string Name { get; set; }
+            /// <summary>
+            /// Name of the monitor.
+            /// </summary>
             public string Description { get; set; }
+            /// <summary>
+            /// Current states of the monitor.
+            /// </summary>
             public DisplayDeviceStateFlags StateFlags { get; set; }
+            /// <summary>
+            /// Device interface name and GUID. Can be used with SetupAPI.
+            /// </summary>
             public string InterfaceName { get; set; }
         }
 
+        /// <summary>
+        /// Index of the adapter/display.
+        /// </summary>
         public int DisplayIndex { get; set; }
+        /// <summary>
+        /// Adapter path.
+        /// </summary>
         public string AdapterName { get; set; }
+        /// <summary>
+        /// Name of the adapter.
+        /// </summary>
         public string AdapterDescription { get; set; }
+        /// <summary>
+        /// Current states of the adapter.
+        /// </summary>
         public DisplayDeviceStateFlags AdapterStateFlags { get; set; }
+        /// <summary>
+        /// All monitors associated with the adapter.
+        /// </summary>
         public Monitor[] Monitors { get; set; }
 
+
+        /// <summary>
+        /// Retrieves information about the adapter/display and its associated monitors.
+        /// </summary>
+        /// <param name="displayIndex">Adapter/display of interest.</param>
         public static DisplayInformation GetAdapterAndDisplayInformation(int displayIndex)
         {
             displayIndex = Math.Max(displayIndex, 0);
@@ -75,6 +157,11 @@ public static DisplayInformation GetAdapterAndDisplayInformation(int displayInde
             return displayInfo;
         }
 
+        /// <summary>
+        /// Lists all displays on the system.
+        /// </summary>
+        /// <param name="doOnlyListAttached">Determines if only displays/adapters that are attached to the desktop should be considered.</param>
+        /// <returns>Can be empty if no adapters/displays are present.</returns>
         public static DisplayInformation[] EnumerateAllDisplays(bool doOnlyListAttached = false)
         {
             var displayInformations = new List<DisplayInformation>();
@@ -119,6 +206,9 @@ public static DisplayInformation[] EnumerateAllDisplays(bool doOnlyListAttached
             return displayInformations.ToArray();
         }
 
+        /// <summary>
+        /// Find index of primary display/adapter.
+        /// </summary>
         public static int FindPrimaryDisplayIndex()
         {
             var devices = EnumerateAllDisplays(true);

DisplaySettings/Source/DisplaySettings.cs

@@ -5,26 +5,66 @@
 
 namespace DisplaySettings
 {
+    /// <summary>
+    /// Holds settings for a display.
+    /// </summary>
     public sealed class DisplaySettings
     {
+        /// <summary>
+        /// Result of display settings change operation. See <see cref="ChangeDisplaySettings(DisplaySettings)"/>.
+        /// </summary>
         public sealed class DisplaySettingsChangedResult
         {
+            /// <summary>
+            /// Possible status code of native <see href="https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-changedisplaysettingsexa">ChangeDisplaySettingsEx</see>function.
+            /// </summary>
             public enum ChangeStatus : int
             {
+                /// <summary>
+                /// The settings change was successful.
+                /// </summary>
                 SUCCESSFUL = 0,
+                /// <summary>
+                /// The computer must be restarted for the graphics mode to work.
+                /// </summary>
                 RESTART = 1,
+                /// <summary>
+                /// The display driver failed the specified graphics mode.
+                /// </summary>
                 FAILED = -1,
+                /// <summary>
+                /// The graphics mode is not supported.
+                /// </summary>
                 BADMODE = -2,
+                /// <summary>
+                /// Unable to write settings to the registry.
+                /// </summary>
                 NOTUPDATED = -3,
+                /// <summary>
+                /// An invalid set of flags was passed in.
+                /// </summary>
                 BADFLAGS = -4,
+                /// <summary>
+                /// An invalid parameter was passed in. This can include an invalid flag or combination of flags.
+                /// </summary>
                 BADPARAM = -5,
+                /// <summary>
+                /// The settings change was unsuccessful because the system is DualView capable.
+                /// </summary>
                 BADDUALVIEW = -6
             }
 
+            /// <summary>
+            /// Return status reported by <see href="https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-changedisplaysettingsexa">ChangeDisplaySettingsEx</see>.
+            /// </summary>
             public ChangeStatus Status { get; private set; }
+            /// <summary>
+            /// Description of the result.
+            /// </summary>
             public string Description { get; private set; }
 
-            public DisplaySettingsChangedResult(ChangeStatus status)
+
+            internal DisplaySettingsChangedResult(ChangeStatus status)
             {
                 Status = status;
                 switch (Status)
@@ -59,39 +99,92 @@ public DisplaySettingsChangedResult(ChangeStatus status)
                 };
             }
 
-            public DisplaySettingsChangedResult(int status) : this((ChangeStatus)status)
+            internal DisplaySettingsChangedResult(int status) : this((ChangeStatus)status)
             {
             }
         }
 
+        /// <summary>
+        /// Type of the display settings to report, either the currently set or those stored in the registry. See <see cref="GetDisplaySettings(int, SettingsType)"/>.
+        /// </summary>
         public enum SettingsType : int
         {
+            /// <summary>
+            /// Use current settings.
+            /// </summary>
             Current = ENUM_CURRENT_SETTINGS,
+            /// <summary>
+            /// Use settings stored in registry.
+            /// </summary>
             Registry = ENUM_REGISTRY_SETTINGS
         }
 
+        /// <summary>
+        /// Graphics mode.
+        /// </summary>
         public sealed class GraphicsMode
         {
+            /// <summary>
+            /// Index of the mode.
+            /// </summary>
             public int Index { get; set; }
+            /// <summary>
+            /// Width of the resolution in pixels.
+            /// </summary>
             public int Width { get; set; }
+            /// <summary>
+            /// Height of the resolution in pixels.
+            /// </summary>
             public int Height { get; set; }
+            /// <summary>
+            /// Vertical refresh rate in Hz.
+            /// </summary>
             public int RefreshRate { get; set; }
+            /// <summary>
+            /// Bit depth in total bits per pixel for all channels.
+            /// </summary>
             public int BitDepth { get; set; }
         }
 
+        /// <summary>
+        /// Position of upper left corner of a display in desktop configuration. The primary display is always at (0,0).
+        /// </summary>
         public struct Position
         {
+            /// <summary>
+            /// X
+            /// </summary>
             public int X { get; set; }
+            /// <summary>
+            /// Y
+            /// </summary>
             public int Y { get; set; }
         }
 
 
+        /// <summary>
+        /// Index of the display/adapter.
+        /// </summary>
         public int DisplayIndex { get; set; }
+        /// <summary>
+        /// Graphics mode.
+        /// </summary>
         public GraphicsMode Mode { get; set; }
+        /// <summary>
+        /// Position in desktop configuration.
+        /// </summary>
         public Position DesktopPosition { get; set; }
+        /// <summary>
+        /// Whether the display/adapter is attached to the desktop.
+        /// </summary>
         public bool IsAttached { get; set; }
 
 
+        /// <summary>
+        /// Change settings of a display.
+        /// </summary>
+        /// <param name="displaySettings">The settings to apply.</param>
+        /// <returns>Result of the operation including a description.</returns>
         public static DisplaySettingsChangedResult ChangeDisplaySettings(DisplaySettings displaySettings)
         {
             displaySettings.DisplayIndex = Math.Max(displaySettings.DisplayIndex, 0);
@@ -129,6 +222,11 @@ public static DisplaySettingsChangedResult ChangeDisplaySettings(DisplaySettings
             }
         }
 
+        /// <summary>
+        /// Retrieve display settings.
+        /// </summary>
+        /// <param name="displayIndex">Index of the display/adapter of interest.</param>
+        /// <param name="type">Whether to retrieve the currently active settings or those stored in the registry for that display/adapter.</param>
         public static DisplaySettings GetDisplaySettings(int displayIndex, SettingsType type = SettingsType.Current)
         {
             displayIndex = Math.Max(displayIndex, 0);
@@ -173,6 +271,10 @@ public static DisplaySettings GetDisplaySettings(int displayIndex, SettingsType
             return displaySettings;
         }
 
+        /// <summary>
+        /// List all graphics modes supported by a display.
+        /// </summary>
+        /// <param name="displayIndex">Index of the display/adapter of interest.</param>
         public static GraphicsMode[] EnumerateAllDisplayModes(int displayIndex)
         {
             var displayModes = new List<GraphicsMode>();

DisplaySettings/Source/Util.cs

@@ -4,8 +4,16 @@
 
 namespace DisplaySettings
 {
+    /// <summary>
+    /// Holds various utility methods.
+    /// </summary>
     public static class Util
     {
+        /// <summary>
+        /// Get name for commonly used bit depths.
+        /// </summary>
+        /// <param name="bitDepth">Bit depth in bits per pixel for all channels.</param>
+        /// <returns><c>High Color</c> for 24 bit, <c>True Color</c> for 32 bit, empty string for all other bit depths.</returns>
         public static string BitDepthToName(int bitDepth)
         {
             switch (bitDepth)