Release 2.0.5.2 - Nuget - Update and package documentation + Readme

Author: Liryna

DokanNet/Dokan.cs

@@ -17,7 +17,7 @@ public class Dokan : IDisposable
         /// <summary>
         /// Initialize all required Dokan internal resources.
         /// 
-        /// This needs to be called only once before trying to use <see cref="Mount"/> or <see cref="CreateFileSystem"/> for the first time.
+        /// This needs to be called only once before trying to use <see cref="DokanInstance.DokanInstance"/> for the first time.
         /// Otherwise both will fail and raise an exception.
         /// </summary>
         /// <param name="logger"><see cref="ILogger"/> that will log all DokanNet debug informations.</param>
@@ -64,7 +64,7 @@ public bool RemoveMountPoint(string mountPoint)
         /// <summary>
         /// Dokan User FS file-change notifications
         /// </summary>
-        /// <remarks> If <see cref="DokanOptions.EnableNotificationAPI"/> is passed to <see cref="Dokan.Mount"/>,
+        /// <remarks> If <see cref="DokanOptions.EnableNotificationAPI"/> is passed to <see cref="DOKAN_OPTIONS.Options"/>,
         /// the application implementing the user file system can notify
         /// the Dokan kernel driver of external file- and directory-changes.
         /// 
@@ -84,7 +84,7 @@ public class Notify
             /// <summary>
             /// Notify Dokan that a file or directory has been created.
             /// </summary>
-            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanCreateFileSystem"/></param>
+            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanInstance.DokanInstance"/></param>
             /// <param name="filePath">Absolute path to the file or directory, including the mount-point of the file system.</param>
             /// <param name="isDirectory">Indicates if the path is a directory.</param>
             /// <returns>true if the notification succeeded.</returns>
@@ -96,7 +96,7 @@ public static bool Create(DokanInstance dokanInstance, string filePath, bool isD
             /// <summary>
             /// Notify Dokan that a file or directory has been deleted.
             /// </summary>
-            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanCreateFileSystem"/></param>
+            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanInstance.DokanInstance"/></param>
             /// <param name="filePath">Absolute path to the file or directory, including the mount-point of the file system.</param>
             /// <param name="isDirectory">Indicates if the path is a directory.</param>
             /// <returns>true if notification succeeded.</returns>
@@ -109,7 +109,7 @@ public static bool Delete(DokanInstance dokanInstance, string filePath, bool isD
             /// <summary>
             /// Notify Dokan that file or directory attributes have changed.
             /// </summary>
-            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanCreateFileSystem"/></param>
+            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanInstance.DokanInstance"/></param>
             /// <param name="filePath">Absolute path to the file or directory, including the mount-point of the file system.</param>
             /// <returns>true if notification succeeded.</returns>
             /// <remarks><see cref="DokanOptions.EnableNotificationAPI"/> must be set in the mount options for this to succeed.</remarks>
@@ -121,7 +121,7 @@ public static bool Update(DokanInstance dokanInstance, string filePath)
             /// <summary>
             /// Notify Dokan that file or directory extended attributes have changed.
             /// </summary>
-            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanCreateFileSystem"/></param>
+            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanInstance.DokanInstance"/></param>
             /// <param name="filePath">Absolute path to the file or directory, including the mount-point of the file system.</param>
             /// <returns>true if notification succeeded.</returns>
             /// <remarks><see cref="DokanOptions.EnableNotificationAPI"/> must be set in the mount options for this to succeed.</remarks>
@@ -134,7 +134,7 @@ public static bool XAttrUpdate(DokanInstance dokanInstance, string filePath)
             /// Notify Dokan that a file or directory has been renamed.
             /// This method supports in-place rename for file/directory within the same parent.
             /// </summary>
-            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanCreateFileSystem"/></param>
+            /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanInstance.DokanInstance"/></param>
             /// <param name="oldPath">Old, absolute path to the file or directory, including the mount-point of the file system.</param>
             /// <param name="newPath">New, absolute path to the file or directory, including the mount-point of the file system.</param>
             /// <param name="isDirectory">Indicates if the path is a directory.</param>
@@ -150,6 +150,10 @@ public static bool Rename(DokanInstance dokanInstance, string oldPath, string ne
             }
         }
 
+        /// <summary>
+        /// Dispose the native Dokan Library resources
+        /// </summary>
+        /// <param name="disposing">Whether this was called from <see cref="Dispose()"/></param>
         protected virtual void Dispose(bool disposing)
         {
             if (!_disposed)
@@ -165,14 +169,19 @@ protected virtual void Dispose(bool disposing)
             }
         }
 
+        /// <summary>
+        /// Dispose the native Dokan Library resources
+        /// </summary>
         public void Dispose()
         {
             // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
             Dispose(disposing: true);
             GC.SuppressFinalize(this);
         }
 
-        // override finalizer only if 'Dispose(bool disposing)' has code to free unmanaged resources
+        /// <summary>
+        /// Override finalizer only if 'Dispose(bool disposing)' has code to free unmanaged resources
+        /// </summary>
         ~Dokan()
         {
             // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method

DokanNet/DokanInstance.cs

@@ -5,7 +5,7 @@
 namespace DokanNet
 {
     /// <summary>
-    /// Created by <see cref="Dokan.CreateFileSystem"/>.
+    /// Created by <see cref="DokanInstance.DokanInstance"/>.
     /// It holds all the resources required to be alive for the time of the mount.
     /// </summary>
     public class DokanInstance : IDisposable
@@ -49,6 +49,10 @@ private static DOKAN_OPERATIONS PrepareOperations(ILogger logger, IDokanOperatio
         internal DokanHandle DokanHandle { get; private set; }
         private readonly object _disposeLock;
         private bool _disposed = false;
+
+        /// <summary>
+        /// Whether the object was already disposed.
+        /// </summary>
         public bool IsDisposed
         {
             get { lock (_disposeLock) return _disposed; }
@@ -68,6 +72,10 @@ internal DokanInstance(ILogger logger, DOKAN_OPTIONS options, IDokanOperations o
             DokanHandle = handle;
         }
 
+        /// <summary>
+        /// Dispose the native Dokan Library resources
+        /// </summary>
+        /// <param name="disposing">Whether this was called from <see cref="Dispose()"/></param>
         protected virtual void Dispose(bool disposing)
         {
             lock (_disposeLock)
@@ -76,7 +84,6 @@ protected virtual void Dispose(bool disposing)
                 {
                     if (disposing)
                     {
-                        // Dispose managed state (managed objects)
                         DokanHandle?.Dispose();     // This calls DokanCloseHandle and waits for dismount
                         DokanOptions?.Dispose();    // After that, it is safe to free unmanaged memory
                         DokanOperations?.Dispose();
@@ -94,12 +101,18 @@ protected virtual void Dispose(bool disposing)
             }
         }
 
+        /// <summary>
+        /// Destructor that force dispose
+        /// </summary>
         ~DokanInstance()
         {
             // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
             Dispose(disposing: false);
         }
 
+        /// <summary>
+        /// Dispose the native Dokan Library resources
+        /// </summary>
         public void Dispose()
         {
             // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method

DokanNet/DokanInstanceBuilder.cs

@@ -9,19 +9,32 @@
 
 namespace DokanNet
 {
+    /// <summary>
+    /// Dokan FileSystem build helper. Allows to create one or multiple <see cref="DokanInstance"/> based on a given configuration.
+    /// </summary>
     public class DokanInstanceBuilder
     {
+        /// <summary>
+        /// Delegate used by <see cref="ConfigureOptions"/> to customize th internal <see cref="DOKAN_OPTIONS"/>.
+        /// </summary>
         public delegate void OptionsConfigurationDelegate(DOKAN_OPTIONS options);
+
         /// <summary>
         /// The Dokan version that DokanNet is compatible with.
         /// </summary>
         /// <see cref="DOKAN_OPTIONS.Version"/>
         public const ushort DOKAN_VERSION = 200;
+
         private readonly DOKAN_OPTIONS _options;
+
         [SuppressMessage("CodeQuality", "IDE0052:Remove unread private members", Justification = "Dokan instance isn't really needed, a reference is kept to enforce a workflow")]
         private readonly Dokan _dokan;
+
         private ILogger _logger;
 
+        /// <summary>
+        /// Constructure an object with a <see cref="NullLogger"/> and default <see cref="DOKAN_OPTIONS"/> that will use the given <paramref name="dokan"/>.
+        /// </summary>
         public DokanInstanceBuilder(Dokan dokan)
         {
             _logger = new NullLogger();
@@ -40,21 +53,40 @@ public DokanInstanceBuilder(Dokan dokan)
             };
             _dokan = dokan;
         }
+
+        /// <summary>
+        /// Allows to set a custom <see cref="ILogger"/> like <see cref="Logger"/>, <see cref="TraceLogger"/> to be used
+        /// for the instance created by <see cref="Build"/>.
+        /// </summary>
         public DokanInstanceBuilder ConfigureLogger(Func<ILogger> IlogegrFactory)
         {
             _logger = IlogegrFactory();
             return this;
         }
+
+        /// <summary>
+        /// Allows to personalize the <see cref="DOKAN_OPTIONS"/> use for <see cref="Build"/>.
+        /// </summary>
         public DokanInstanceBuilder ConfigureOptions(OptionsConfigurationDelegate optionsConfigurationDelegate)
         {
             optionsConfigurationDelegate(_options);
             return this;
         }
+
+        /// <summary>
+        /// Verify that the provided configuration is valid.
+        /// Note: Has no effect for now.
+        /// </summary>
         public DokanInstanceBuilder Validate()
         {
             // throw on errors
             return this;
         }
+
+        /// <summary>
+        /// Create a <see cref="DokanInstance"/> based on the previously provided information
+        /// through <see cref="ConfigureOptions"/> and <see cref="ConfigureLogger"/>.
+        /// </summary>
         public DokanInstance Build(IDokanOperations operations)
         {
             return new DokanInstance(_logger, _options, operations);

DokanNet/DokanNet.csproj

@@ -8,11 +8,12 @@
 
 This is a .NET wrapper over Dokan, and allows you to create your own file systems in Windows.</Description>
     <Copyright>Copyright (C) 2022</Copyright>
-    <Version>2.0.5.1</Version>
-    <AssemblyVersion>2.0.5.1</AssemblyVersion>
-    <FileVersion>2.0.5.1</FileVersion>
+    <Version>2.0.5.2</Version>
+    <AssemblyVersion>2.0.5.2</AssemblyVersion>
+    <FileVersion>2.0.5.2</FileVersion>
     <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
+	<PackageReadmeFile>README.md</PackageReadmeFile>
     <Company>Dokan-dev</Company>
     <Authors>AdrienJ, MaximeC, Hiroki Asakawa</Authors>
     <PackageProjectUrl>https://dokan-dev.github.io/</PackageProjectUrl>
@@ -34,6 +35,7 @@ This is a .NET wrapper over Dokan, and allows you to create your own file system
 
   <ItemGroup>
     <None Include="..\dokan_logo.png" Pack="true" PackagePath="\" />
+	<None Include="..\README.md" Pack="true" PackagePath="\"/>
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">

DokanNet/DokanOperationProxy.cs

@@ -155,16 +155,6 @@ public delegate NtStatus SetFileSecurityDelegate(
             uint rawSecurityDescriptorLength,
             [MarshalAs(UnmanagedType.LPStruct), In /*, Out*/] DokanFileInfo rawFileInfo);
 
-        /// <summary>
-        /// Retrieve all FileStreams informations on the file.
-        /// This is only called if <see cref="DokanOptions.AltStream"/> is enabled.
-        /// </summary>
-        /// <remarks>Supported since 0.8.0. 
-        /// You must specify the version at <see cref="DOKAN_OPTIONS.Version"/>.</remarks>
-        /// <param name="rawFileName">Filename</param>
-        /// <param name="rawFillFindData">A <see cref="IntPtr"/> to a <see cref="FILL_FIND_STREAM_DATA"/>.</param>
-        /// <param name="rawFileInfo">A <see cref="DokanFileInfo"/>.</param>
-        /// <returns></returns>
         public delegate NtStatus FindStreamsDelegate(
             [MarshalAs(UnmanagedType.LPWStr)] string rawFileName,
             IntPtr rawFillFindData,
@@ -781,7 +771,7 @@ public NtStatus FindStreamsProxy(string rawFileName, IntPtr rawFillFindData, Int
         /// <returns>A instance of the specified delegate type.</returns>
         /// <param name="rawDelegate">The unmanaged function pointer to convert. </param>
         /// <typeparam name="TDelegate">The type of the delegate to return. </typeparam>
-        /// <exception cref="T:System.ArgumentException">The <typeparam name="TDelegate" /> generic parameter is not a delegate, or it is an open generic type.</exception>
+        /// <exception cref="T:System.ArgumentException">The <typeparamref name="TDelegate" /> generic parameter is not a delegate, or it is an open generic type.</exception>
         /// <exception cref="T:System.ArgumentNullException">The <paramref name="rawDelegate" /> parameter is null.</exception>
         private static TDelegate GetDataFromPointer<TDelegate>(IntPtr rawDelegate) where TDelegate : class 
         {
@@ -793,10 +783,10 @@ private static TDelegate GetDataFromPointer<TDelegate>(IntPtr rawDelegate) where
         }
 
         /// <summary>
-        /// Call the delegate <paramref name="fill"/> using data in <paramref name="rawFileInfo"/> and <paramref name="fi"/>.
+        /// Call the delegate <paramref name="fill"/> using data in <paramref name="fi"/> and <paramref name="findStreamContext"/>.
         /// </summary>
         /// <param name="fill">The delegate of type <see cref="FILL_FIND_STREAM_DATA"/> to be called.</param>
-        /// <param name="rawFileInfo">A <see cref="DokanFileInfo"/> to be used when calling <paramref name="fill"/>.</param>
+        /// <param name="findStreamContext">A <see cref="IntPtr"/> to be used when calling <paramref name="fill"/>.</param>
         /// <param name="fi">A <see cref="FileInformation"/> with information to be used when calling <paramref name="fill"/>.</param>
         /// <returns>Whether the buffer is full or not.</returns>
         private static bool AddTo(FILL_FIND_STREAM_DATA fill, IntPtr findStreamContext, FileInformation fi)

DokanNet/Extensions.cs

@@ -5,12 +5,15 @@
 
 namespace DokanNet
 {
+    /// <summary>
+    /// <see cref="DokanInstance"/> extensions allowing to check whether it is running or to wait until it is unmount.
+    /// </summary>
     public static class Extensions
     {
         /// <summary>
         /// Check if the FileSystem is still running or not.
         /// </summary>
-        /// <param name="dokanInstance">The dokan mount context created by <see cref="CreateFileSystem"/>.</param>
+        /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanInstance.DokanInstance"/>.</param>
         /// <returns>Whether the FileSystem is still running or not.</returns>
         public static Boolean IsFileSystemRunning(this DokanInstance dokanInstance)
         {
@@ -20,9 +23,9 @@ public static Boolean IsFileSystemRunning(this DokanInstance dokanInstance)
         /// <summary>
         /// Wait until the FileSystem is unmount.
         /// </summary>
-        /// <param name="dokanInstance">The dokan mount context created by <see cref="CreateFileSystem"/>.</param>
-        /// <param name="milliSeconds">The time-out interval, in milliseconds. If a nonzero value is specified, the function waits until the object is signaled or the interval elapses. If <param name="milliSeconds"> is zero,
-        /// the function does not enter a wait state if the object is not signaled; it always returns immediately. If <param name="milliSeconds"> is INFINITE, the function will return only when the object is signaled.</param>
+        /// <param name="dokanInstance">The dokan mount context created by <see cref="DokanInstance.DokanInstance"/>.</param>
+        /// <param name="milliSeconds">The time-out interval, in milliseconds. If a nonzero value is specified, the function waits until the object is signaled or the interval elapses. If set to zero,
+        /// the function does not enter a wait state if the object is not signaled; it always returns immediately. If set to INFINITE, the function will return only when the object is signaled.</param>
         /// <returns>See <a href="https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject">WaitForSingleObject</a> for a description of return values.</returns>
         public static UInt32 WaitForFileSystemClosed(this DokanInstance dokanInstance, UInt32 milliSeconds)
         {

DokanNet/FileAccess.cs

@@ -27,7 +27,7 @@ public enum FileAccess : long
         /// </summary>
         /// \native
         /// \table
-        /// \nativeconst{FILE_READ_DATA,0x00000001,File & pipe}
+        /// \nativeconst{FILE_READ_DATA,0x00000001,File &amp; pipe}
         /// \nativeconst{FILE_LIST_DIRECTORY,0x00000001,Directory}
         /// \endtable
         /// \endnative
@@ -38,7 +38,7 @@ public enum FileAccess : long
         /// </summary>
         /// \native
         /// \table
-        /// \nativeconst{FILE_WRITE_DATA,0x00000002,File & pipe}
+        /// \nativeconst{FILE_WRITE_DATA,0x00000002,File &amp; pipe}
         /// \nativeconst{FILE_ADD_FILE,0x00000002,Directory}
         /// \endtable
         /// \endnative
@@ -61,7 +61,7 @@ public enum FileAccess : long
         /// </summary>
         /// \native
         /// \table
-        /// \nativeconst{FILE_READ_EA,0x00000008,File & directory}
+        /// \nativeconst{FILE_READ_EA,0x00000008,File &amp; directory}
         /// \endtable
         /// \endnative
         ReadExtendedAttributes = 1L << 3,
@@ -71,7 +71,7 @@ public enum FileAccess : long
         /// </summary>
         /// \native
         /// \table
-        /// \nativeconst{FILE_WRITE_EA,0x00000010,File & directory}
+        /// \nativeconst{FILE_WRITE_EA,0x00000010,File &amp; directory}
         /// \endtable
         /// \endnative
         WriteExtendedAttributes = 1L << 4,