Merge pull request #47 from Arlodotexe/general-cleanup

Release 0.9.3 (general cleanup)

src/Archive/ReadOnlyZipArchiveFolder.cs

@@ -89,21 +89,23 @@ internal ReadOnlyZipArchiveFolder(ZipArchive archive, string name, ReadOnlyZipAr
     /// <inheritdoc/>
     public string Name { get; }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// Gets the relative path from the root of the archive.
+    /// </summary>
     public string Path { get; }
 
     /// <summary>
-    /// A folder that represents the root of the archive.
+    /// Gets the folder that represents the root of the archive.
     /// </summary>
     public IFolder RootFolder { get; }
 
     /// <summary>
-    /// The file that this archive originated from.
+    /// Gets the file that this archive originated from.
     /// </summary>
     public IFile? SourceFile { get; }
 
     /// <summary>
-    /// The instance used to explore the archive.
+    /// Gets the instance used to explore the archive.
     /// </summary>
     public ZipArchive? Archive { get; protected set; }
 

src/Extensions/CopyAndMoveExtensions.cs

@@ -15,7 +15,7 @@ public static partial class ModifiableFolderExtensions
     /// <param name="destinationFolder">The folder where the copy is created.</param>
     /// <param name="fileToCopy">The file to be copied into this folder.</param>
     /// <param name="overwrite"><code>true</code> if the destination file can be overwritten; otherwise, <c>false</c>.</param>
-    /// <param name="cancellationToken">The cancellation token to observe.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
     public static async Task<IChildFile> CreateCopyOfAsync<T>(this IModifiableFolder destinationFolder, T fileToCopy, bool overwrite = default, CancellationToken cancellationToken = default)
         where T : IFile
     {
@@ -68,7 +68,7 @@ public static async Task<IChildFile> CreateCopyOfAsync<T>(this IModifiableFolder
     /// <param name="fileToMove">The file being moved into this folder.</param>
     /// <param name="source">The folder that <paramref name="fileToMove"/> is being moved from.</param>
     /// <param name="overwrite"><code>true</code> if the destination file can be overwritten; otherwise, <c>false</c>.</param>
-    /// <param name="cancellationToken">The cancellation token to observe.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
     public static async Task<IChildFile> MoveFromAsync<T>(this IModifiableFolder destinationFolder, T fileToMove, IModifiableFolder source, bool overwrite = default, CancellationToken cancellationToken = default)
         where T : IFile, IStorableChild
     {

src/Extensions/IFastFileCopy.cs

@@ -15,7 +15,8 @@ public interface IFastFileCopy<in T> : IModifiableFolder
     /// Creates a copy of the provided file within this folder.
     /// </summary>
     /// <param name="fileToCopy">The file to be copied into this folder.</param>
-    /// <param name="overwrite"><code>true</code> if the destination file can be overwritten; otherwise, <c>false</c>.</param>
-    /// <param name="cancellationToken">The cancellation token to observe.</param>
-    public Task<IChildFile> CreateCopyOfAsync(T fileToCopy, bool overwrite = default, CancellationToken cancellationToken = default);
+    /// <param name="overwrite">If there is an existing destination file, <c>true</c> will overwrite it; otherwise <c>false</c> and the existing file is opened.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <returns>The newly created (or opened if existing) file.</returns>
+    Task<IChildFile> CreateCopyOfAsync(T fileToCopy, bool overwrite = default, CancellationToken cancellationToken = default);
 }

src/Extensions/IFastFileMove.cs

@@ -16,7 +16,8 @@ public interface IFastFileMove<in T> : IModifiableFolder
     /// </summary>
     /// <param name="fileToMove">The file being moved into this folder.</param>
     /// <param name="source">The folder that <paramref name="fileToMove"/> is being moved from.</param>
-    /// <param name="overwrite"><code>true</code> if the destination file can be overwritten; otherwise, <c>false</c>.</param>
-    /// <param name="cancellationToken">The cancellation token to observe.</param>
-    public Task<IChildFile> MoveFromAsync(T fileToMove, IModifiableFolder source, bool overwrite = default, CancellationToken cancellationToken = default);
+    /// <param name="overwrite">If there is an existing destination file, <c>true</c> will overwrite it; otherwise <c>false</c> and the existing file is opened.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <returns>The newly created (or opened if existing) file.</returns>
+    Task<IChildFile> MoveFromAsync(T fileToMove, IModifiableFolder source, bool overwrite = default, CancellationToken cancellationToken = default);
 }

src/Extensions/IFastGetFirstItemByName.cs

@@ -14,7 +14,7 @@ public interface IFastGetFirstByName : IFolder
     /// Retrieves the first <see cref="IStorable"/> item which has the provided <paramref name="name"/>.
     /// </summary>
     /// <param name="name">The <see cref="IStorable.Name"/> of the storable item to retrieve.</param>
-    /// <param name="cancellationToken">The cancellation token to observe.</param>
-    /// <returns></returns>
-    public Task<IStorableChild> GetFirstByNameAsync(string name, CancellationToken cancellationToken = default);
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <returns>The first <see cref="IStorable"/> with the requested <paramref name="name"/>.</returns>
+    Task<IStorableChild> GetFirstByNameAsync(string name, CancellationToken cancellationToken = default);
 }

src/Extensions/IFastGetItem.cs

@@ -15,6 +15,6 @@ public interface IFastGetItem : IFolder
     /// </summary>
     /// <param name="id">The <see cref="IStorable.Id"/> of the storable item to retrieve.</param>
     /// <param name="cancellationToken">The cancellation token to observe.</param>
-    /// <returns></returns>
-    public Task<IStorableChild> GetItemAsync(string id, CancellationToken cancellationToken = default);
+    /// <returns>An instance of <see cref="IStorableChild"/> with the requested <paramref name="id"/>.</returns>
+    Task<IStorableChild> GetItemAsync(string id, CancellationToken cancellationToken = default);
 }

src/Extensions/IFastGetItemRecursive.cs

@@ -15,6 +15,6 @@ public interface IFastGetItemRecursive : IFolder
     /// <param name="id">The <see cref="IStorable.Id"/> of the item to crawl.</param>
     /// <param name="cancellationToken">A token to cancel the ongoing operation.</param>
     /// <exception cref="FileNotFoundException">A named item was specified in a folder, but the item wasn't found.</exception>
-    /// <returns></returns>
-    public Task<IStorableChild> GetItemRecursiveAsync(string id, CancellationToken cancellationToken = default);
+    /// <returns>An instance of <see cref="IStorableChild"/> with the requested <paramref name="id"/>.</returns>
+    Task<IStorableChild> GetItemRecursiveAsync(string id, CancellationToken cancellationToken = default);
 }

src/Extensions/IFastGetRoot.cs

@@ -10,6 +10,6 @@ public interface IFastGetRoot : IStorableChild
     /// <summary>
     /// Retrieves the root of this storable item. If this item IS the root, null will be returned instead.
     /// </summary>
-    /// <returns>The root of this storable item</returns>
-    public Task<IFolder?> GetRootAsync();
+    /// <returns>The root parent folder for this storage instance. if any.</returns>
+    Task<IFolder?> GetRootAsync();
 }

src/HttpFile.cs

@@ -54,12 +54,12 @@ public HttpFile(string uri, HttpClient httpClient)
     }
 
     /// <summary>
-    /// The message handler to use for making HTTP requests.
+    /// Gets the message handler to use for making HTTP requests.
     /// </summary>
     public HttpClient Client { get; init; }
 
     /// <summary>
-    /// The http address to GET for the file content.
+    /// Gets the http address to GET for the file content.
     /// </summary>
     public Uri Uri { get; }
 

src/IFile.cs

@@ -5,12 +5,15 @@
 namespace OwlCore.Storage;
 
 /// <summary>
-/// The minimal functional requirements for a file.
+/// The simplest possible representation of a file.
 /// </summary>
 public interface IFile : IStorable
 {
     /// <summary>
-    /// Opens a new stream to the file.
+    /// Opens a new stream to the resource.
     /// </summary>
-    public Task<Stream> OpenStreamAsync(FileAccess accessMode = FileAccess.Read, CancellationToken cancellationToken = default);
+    /// <param name="accessMode">A <see cref="FileAccess"/> value that specifies the operations that can be performed on the file.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <returns>A stream that provides access to this file, with the specified <paramref name="accessMode"/>.</returns>
+    Task<Stream> OpenStreamAsync(FileAccess accessMode = FileAccess.Read, CancellationToken cancellationToken = default);
 }

src/IFolder.cs

@@ -4,12 +4,15 @@
 namespace OwlCore.Storage;
 
 /// <summary>
-/// The minimal functional requirements for a folder.
+/// The simplest possible representation of a folder.
 /// </summary>
 public interface IFolder : IStorable
 {
     /// <summary>
     /// Retrieves the folders in this directory.
     /// </summary>
-    public IAsyncEnumerable<IStorableChild> GetItemsAsync(StorableType type = StorableType.All, CancellationToken cancellationToken = default);
+    /// <param name="type">The type of items to retrieve.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <returns>An async enumerable that yields the requested items.</returns>
+    IAsyncEnumerable<IStorableChild> GetItemsAsync(StorableType type = StorableType.All, CancellationToken cancellationToken = default);
 }

src/IFolderWatcher.cs

@@ -9,7 +9,7 @@ namespace OwlCore.Storage;
 public interface IFolderWatcher : INotifyCollectionChanged, IDisposable, IAsyncDisposable
 {
     /// <summary>
-    /// The folder being watched for changes.
+    /// Gets the folder being watched for changes.
     /// </summary>
-    public IMutableFolder Folder { get; }
+    IMutableFolder Folder { get; }
 }

src/IModifiableFolder.cs

@@ -13,23 +13,26 @@ public interface IModifiableFolder : IMutableFolder
     /// Deletes the provided storable item from this folder.
     /// </summary>
     /// <param name="item">The item to be removed from this folder.</param>
-    /// <param name="cancellationToken">The cancellation token to observe.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
     /// <exception cref="FileNotFoundException">The item was not found in the provided folder.</exception>
-    public Task DeleteAsync(IStorableChild item, CancellationToken cancellationToken = default);
+    /// <returns>A <see cref="Task"/> that represents the asynchronous operation.</returns>
+    Task DeleteAsync(IStorableChild item, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Creates a new folder with the desired name inside this folder.
     /// </summary>
     /// <param name="name">The name of the new folder.</param>
     /// <param name="overwrite"><code>true</code> if the destination file can be overwritten; otherwise, <c>false</c>.</param>
-    /// <param name="cancellationToken">The cancellation token to observe.</param>
-    public Task<IChildFolder> CreateFolderAsync(string name, bool overwrite = default, CancellationToken cancellationToken = default);
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <returns>The newly created (or opened if existing) folder.</returns>
+    Task<IChildFolder> CreateFolderAsync(string name, bool overwrite = default, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Creates a new file with the desired name inside this folder.
     /// </summary>
     /// <param name="name">The name of the new file.</param>
     /// <param name="overwrite"><code>true</code> if the destination file can be overwritten; otherwise, <c>false</c>.</param>
-    /// <param name="cancellationToken">The cancellation token to observe.</param>
-    public Task<IChildFile> CreateFileAsync(string name, bool overwrite = default, CancellationToken cancellationToken = default);
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <returns>The newly created (or opened if existing) file.</returns>
+    Task<IChildFile> CreateFileAsync(string name, bool overwrite = default, CancellationToken cancellationToken = default);
 }

src/IMutableFolder.cs

@@ -11,6 +11,6 @@ public interface IMutableFolder : IFolder
     /// <summary>
     /// Asynchronously retrieves a disposable object which can notify of changes to the folder.
     /// </summary>
-    /// <returns>A Task representing the asynchronous operation. The result is a disposable object which can notify of changes to the folder.</returns>
-    public Task<IFolderWatcher> GetFolderWatcherAsync(CancellationToken cancellationToken = default);
+    /// <returns>A disposable object which can notify of changes to the folder.</returns>
+    Task<IFolderWatcher> GetFolderWatcherAsync(CancellationToken cancellationToken = default);
 }

src/IStorable.cs

@@ -1,24 +1,26 @@
 namespace OwlCore.Storage;
 
 /// <summary>
-/// The absolute minimum requirements for all storable items.
+/// Represents an item that can be stored or retrieved from a storage source.
 /// </summary>
 public interface IStorable
 {
     /// <summary>
-    /// A unique and consistent identifier for this file or folder. This dedicated resource identifier is used to identify the exact file you're pointing to.
+    /// Gets a unique identifier for this item that is consistent across reruns.
     /// </summary>
     /// <remarks>
-    /// Uri paths, especially those from cloud storage, can change regularly (e.g. when re-authenticating), and some files/folders aren't even addressable, meaning paths can't be used as a reliable content identifier.
-    /// Also, custom and especially cloud file systems often use a predictable or custom ID as the primary-key in a flat or near-flat database table of files and folders. This also means that names aren't guaranteed to be unique within a folder.
+    /// <para/> Custom and (especially cloud) file systems often use a flat or near-flat database and a predictable or custom ID as the primary-key, which can be used as an Id.
+    /// <para/> Paths that are unique to the local file system can be used as an Id.
+    /// <para/> Uri-based resource paths that change (e.g. when re-authenticating) should not be used as an Id.
+    /// <para/> Names aren't guaranteed to be non-empty or unique within or across folders, and should not be used as an Id.
     ///
     /// <para />
-    /// Instead, since the underlying implementation knows the requirements, it can supply what data it has as long as it uniquely and consistently identifies the content.
+    /// The implementation can use any string data available to produce this ID, so long as it identifies this specific resource across runs.
     /// </remarks>
-    public string Id { get; }
+    string Id { get; }
 
     /// <summary>
-    /// The name of the file or folder, with the extension (if any).
+    /// Gets the name of the item, with the extension (if any).
     /// </summary>
-    public string Name { get; } 
+    string Name { get; } 
 }

src/IStorableChild.cs

@@ -11,5 +11,7 @@ public interface IStorableChild : IStorable
     /// <summary>
     /// Gets the containing folder for this item, if any.
     /// </summary>
-    public Task<IFolder?> GetParentAsync(CancellationToken cancellationToken = default); 
+    /// <param name="cancellationToken">A token that can be used to cancel the ongoing operation.</param>
+    /// <returns>The containing parent folder, if any.</returns>
+    Task<IFolder?> GetParentAsync(CancellationToken cancellationToken = default); 
 }

src/IStorageProperty.cs

@@ -14,10 +14,10 @@ public interface IStorageProperty<T> : IDisposable
     /// <summary>
     /// Gets the current property value.
     /// </summary>
-    public T Value { get; }
+    T Value { get; }
 
     /// <summary>
     /// Raised when the <see cref="Value"/> is updated.
     /// </summary>
-    public event EventHandler<T> ValueUpdated;
+    event EventHandler<T>? ValueUpdated;
 }

src/Internal/LazySeekStream.cs

@@ -8,8 +8,8 @@ namespace OwlCore.Storage;
 /// </summary>
 internal class LazySeekStream : Stream
 {
-    private Stream _originalStream;
-    private MemoryStream _memoryStream;
+    private readonly Stream _originalStream;
+    private readonly MemoryStream _memoryStream;
 
     /// <summary>
     /// Creates a new instance of <see cref="LazySeekStream"/>.

src/Memory/MemoryFolder.cs

@@ -35,7 +35,7 @@ public MemoryFolder(string id, string name)
     public string Name { get; }
 
     /// <summary>
-    /// The parent folder, if any.
+    /// Gets the parent folder, if any.
     /// </summary>
     public MemoryFolder? Parent { get; internal set; }
 

src/OwlCore.Storage.csproj

@@ -14,7 +14,7 @@
     <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
 
     <Author>Arlo Godfrey</Author>
-    <Version>0.9.2</Version>
+    <Version>0.9.3</Version>
     <Product>OwlCore</Product>
     <Description>The most flexible file system abstraction, ever. Built in partnership with the UWP Community.
 
@@ -23,6 +23,11 @@
     <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
     <PackageIcon>logo.png</PackageIcon>
     <PackageReleaseNotes>
+--- 0.9.3 ---
+[Improvements]
+The DirectoryInfo for SystemFolder is now exposed as a public Info property.
+General pass adding missing xmldoc comments to interfaces.
+
 --- 0.9.2 ---
 [Improvements]
 The stream returned by HttpFile.OpenStreamAsync() now includes the value of the Content-Length header as the stream Length.

src/StreamFile.cs

@@ -12,7 +12,7 @@ namespace OwlCore.Storage;
 public class StreamFile : IFile
 {
     /// <summary>
-    /// The stream being accessed for this file.
+    /// Gets the stream being accessed for this file.
     /// </summary>
     public Stream Stream { get; }
 

src/SystemIO/SystemFile.cs

@@ -47,11 +47,13 @@ public SystemFile(FileInfo info)
     /// <inheritdoc />
     public string Name => _name ??= System.IO.Path.GetFileName(Path);
 
-    /// <inheritdoc />
+    /// <summary>
+    /// Gets the path of the file on disk.
+    /// </summary>
     public string Path { get; }
 
     /// <summary>
-    /// The file info for the <see cref="SystemFile"/>.
+    /// Gets the underlying <see cref="FileInfo"/> for this folder.
     /// </summary>
     public FileInfo Info => _info ??= new(Path);