Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Code Quality: Added XML comments for C# source files #13358

Closed
wants to merge 12 commits into from
Closed
3 changes: 3 additions & 0 deletions src/Files.App.BackgroundTasks/UpdateTask.cs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@

namespace Files.App.BackgroundTasks
{
/// <summary>
/// Represents background task to update app components.
/// </summary>
public sealed class UpdateTask : IBackgroundTask
{
public async void Run(IBackgroundTaskInstance taskInstance)
Expand Down
2 changes: 1 addition & 1 deletion src/Files.App.Storage/Files.App.Storage.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,4 @@
<ProjectReference Include="..\Files.Shared\Files.Shared.csproj" />
</ItemGroup>

</Project>
</Project>
5 changes: 4 additions & 1 deletion src/Files.App.Storage/FtpStorage/FtpHelpers.cs
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,10 @@
using System.Threading.Tasks;

namespace Files.App.Storage.FtpStorage
{
{
/// <summary>
/// Provides static helper for FTP storage.
/// </summary>
internal static class FtpHelpers
{
public static string GetFtpPath(string path)
Expand Down
3 changes: 3 additions & 0 deletions src/Files.App.Storage/FtpStorage/FtpManager.cs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@

namespace Files.App.Storage.FtpStorage
{
/// <summary>
/// Provides static handler for FTP storage.
/// </summary>
public static class FtpManager
{
public static readonly Dictionary<string, NetworkCredential> Credentials = new();
Expand Down
3 changes: 3 additions & 0 deletions src/Files.App.Storage/FtpStorage/FtpStorable.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@

namespace Files.App.Storage.FtpStorage
{
/// <summary>
/// Represents a storable resource that resides in FTP storage.
/// </summary>
public abstract class FtpStorable : ILocatableStorable, INestedStorable
{
/// <inheritdoc/>
Expand Down
3 changes: 3 additions & 0 deletions src/Files.App.Storage/FtpStorage/FtpStorageFile.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@

namespace Files.App.Storage.FtpStorage
{
/// <summary>
/// Represents a file that resides in FTP storage.
/// </summary>
public sealed class FtpStorageFile : FtpStorable, IModifiableFile, ILocatableFile, INestedFile
{
public FtpStorageFile(string path, string name, IFolder? parent)
Expand Down
3 changes: 3 additions & 0 deletions src/Files.App.Storage/FtpStorage/FtpStorageFolder.cs
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@

namespace Files.App.Storage.FtpStorage
{
/// <summary>
/// Represents a folder that resides in FTP storage.
/// </summary>
public sealed class FtpStorageFolder : FtpStorable, ILocatableFolder, IModifiableFolder, IFolderExtended, INestedFolder, IDirectCopy, IDirectMove
{
public FtpStorageFolder(string path, string name, IFolder? parent)
Expand Down
154 changes: 77 additions & 77 deletions src/Files.App.Storage/NativeStorage/NativeFolder.cs
Original file line number Diff line number Diff line change
Expand Up @@ -21,83 +21,83 @@ namespace Files.App.Storage.NativeStorage
{
/// <inheritdoc cref="IFolder"/>
public class NativeFolder : NativeStorable<DirectoryInfo>, ILocatableFolder, IModifiableFolder, IMutableFolder, IFolderExtended, INestedFolder, IDirectCopy, IDirectMove
{
{
public NativeFolder(DirectoryInfo directoryInfo, string? name = null)
: base(directoryInfo, name)
{
}

public NativeFolder(string path, string? name = null)
: this(new DirectoryInfo(path), name)
{
}

/// <inheritdoc/>
public virtual Task<INestedFile> GetFileAsync(string fileName, CancellationToken cancellationToken = default)
{
var path = System.IO.Path.Combine(Path, fileName);

if (!File.Exists(path))
throw new FileNotFoundException();

return Task.FromResult<INestedFile>(new NativeFile(path));
}

/// <inheritdoc/>
public virtual Task<INestedFolder> GetFolderAsync(string folderName, CancellationToken cancellationToken = default)
{
var path = System.IO.Path.Combine(Path, folderName);
if (!Directory.Exists(path))
throw new FileNotFoundException();

return Task.FromResult<INestedFolder>(new NativeFolder(path));
}

/// <inheritdoc/>
public virtual async IAsyncEnumerable<INestedStorable> GetItemsAsync(StorableKind kind = StorableKind.All, [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
if (kind == StorableKind.Files)
{
foreach (var item in Directory.EnumerateFiles(Path))
yield return new NativeFile(item);
}
else if (kind == StorableKind.Folders)
{
foreach (var item in Directory.EnumerateDirectories(Path))
yield return new NativeFolder(item);
}
else
{
foreach (var item in Directory.EnumerateFileSystemEntries(Path))
{
if (File.Exists(item))
yield return new NativeFile(item);
else
yield return new NativeFolder(item);
}
}

await Task.CompletedTask;
}
: base(directoryInfo, name)
{
}

public NativeFolder(string path, string? name = null)
: this(new DirectoryInfo(path), name)
{
}

/// <inheritdoc/>
public virtual Task<INestedFile> GetFileAsync(string fileName, CancellationToken cancellationToken = default)
{
var path = System.IO.Path.Combine(Path, fileName);

if (!File.Exists(path))
throw new FileNotFoundException();

return Task.FromResult<INestedFile>(new NativeFile(path));
}

/// <inheritdoc/>
public virtual Task<INestedFolder> GetFolderAsync(string folderName, CancellationToken cancellationToken = default)
{
var path = System.IO.Path.Combine(Path, folderName);
if (!Directory.Exists(path))
throw new FileNotFoundException();

return Task.FromResult<INestedFolder>(new NativeFolder(path));
}

/// <inheritdoc/>
public virtual async IAsyncEnumerable<INestedStorable> GetItemsAsync(StorableKind kind = StorableKind.All, [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
if (kind == StorableKind.Files)
{
foreach (var item in Directory.EnumerateFiles(Path))
yield return new NativeFile(item);
}
else if (kind == StorableKind.Folders)
{
foreach (var item in Directory.EnumerateDirectories(Path))
yield return new NativeFolder(item);
}
else
{
foreach (var item in Directory.EnumerateFileSystemEntries(Path))
{
if (File.Exists(item))
yield return new NativeFile(item);
else
yield return new NativeFolder(item);
}
}

await Task.CompletedTask;
}

/// <inheritdoc/>
public virtual Task DeleteAsync(INestedStorable item, bool permanently = false, CancellationToken cancellationToken = default)
{
_ = permanently;

if (item is ILocatableFile locatableFile)
{
File.Delete(locatableFile.Path);
}
else if (item is ILocatableFolder locatableFolder)
{
Directory.Delete(locatableFolder.Path, true);
}
else
throw new ArgumentException($"Could not delete {item}.");

return Task.CompletedTask;
}
{
_ = permanently;

if (item is ILocatableFile locatableFile)
{
File.Delete(locatableFile.Path);
}
else if (item is ILocatableFolder locatableFolder)
{
Directory.Delete(locatableFolder.Path, true);
}
else
throw new ArgumentException($"Could not delete {item}.");

return Task.CompletedTask;
}

/// <inheritdoc/>
public virtual async Task<INestedStorable> CreateCopyOfAsync(INestedStorable itemToCopy, bool overwrite = default, CancellationToken cancellationToken = default)
Expand Down Expand Up @@ -179,8 +179,8 @@ public virtual Task<INestedFolder> CreateFolderAsync(string desiredName, bool ov

/// <inheritdoc/>
public Task<IFolderWatcher> GetFolderWatcherAsync(CancellationToken cancellationToken = default)
{
return Task.FromResult<IFolderWatcher>(new NativeFolderWatcher(this));
}
}
{
return Task.FromResult<IFolderWatcher>(new NativeFolderWatcher(this));
}
}
}
2 changes: 1 addition & 1 deletion src/Files.App.Storage/NativeStorage/NativeFolderWatcher.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
namespace Files.App.Storage.NativeStorage
{
/// <inheritdoc cref="IFolderWatcher"/>
public sealed class NativeFolderWatcher : IFolderWatcher
public sealed class NativeFolderWatcher : IFolderWatcher
{
private FileSystemWatcher? _fileSystemWatcher;
private NotifyCollectionChangedEventHandler? _collectionChanged;
Expand Down
1 change: 1 addition & 0 deletions src/Files.App.Storage/WindowsStorage/WindowsStorable.cs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ public abstract class WindowsStorable<TStorage> : ILocatableStorable, INestedSto
where TStorage : class, IStorageItem
{
private string? _computedId;

internal readonly TStorage storage;

/// <inheritdoc/>
Expand Down
2 changes: 1 addition & 1 deletion src/Files.App/Actions/BaseUIAction.cs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
namespace Files.App.Actions
{
/// <summary>
/// Represents base class for the UI Actions.
/// Represents base action against UI components.
/// </summary>
internal abstract class BaseUIAction : ObservableObject
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents base action to compress archive.
/// </summary>
Comment on lines +6 to +8
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As you said in your PR, this info is a duplicate info from the class name.

I don't think it's a good practice to add those, it creates twice the same information, and increases the maintenance cost. Instead of having to only modify the name of the function, you have to also modify the comment. And comments are quite often forgettable. A function's name should be usually enough to explain their use.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are going to add docs that will be generated from XML comments. So I just rushed to add comments and so some comments are being redundant. We can improve later, now this PR's purpose is creating practice to add comments on creating a new method, property, class.

internal abstract class BaseCompressArchiveAction : BaseUIAction, IAction
{
protected readonly IContentPageContext context;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action to compress into archive.
/// </summary>
internal sealed class CompressIntoArchiveAction : BaseCompressArchiveAction
{
public override string Label
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action to compress into 7zip.
/// </summary>
internal sealed class CompressIntoSevenZipAction : BaseCompressArchiveAction
{
public override string Label
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action to compress into zip.
/// </summary>
internal sealed class CompressIntoZipAction : BaseCompressArchiveAction
{
public override string Label
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents base action to decompress archive.
/// </summary>
internal abstract class BaseDecompressArchiveAction : BaseUIAction, IAction
{
protected readonly IContentPageContext context;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action to decompress archive inside of the selected archive.
/// </summary>
internal sealed class DecompressArchive : BaseDecompressArchiveAction
{
public override string Label
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action to decompress archive here.
/// </summary>
internal sealed class DecompressArchiveHere : BaseDecompressArchiveAction
{
public override string Label
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action to decompress archive to child folder.
/// </summary>
internal sealed class DecompressArchiveToChildFolderAction : BaseDecompressArchiveAction
{
public override string Label
Expand Down
3 changes: 3 additions & 0 deletions src/Files.App/Actions/Content/Background/BaseSetAsAction.cs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents base action to set image as.
/// </summary>
internal abstract class BaseSetAsAction : ObservableObject, IAction
{
protected readonly IContentPageContext context;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action to set image as Windows lockscreen background.
/// </summary>
internal class SetAsLockscreenBackgroundAction : BaseSetAsAction
{
public override string Label
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action set image as Windows slideshow background.
/// </summary>
internal class SetAsSlideshowBackgroundAction : BaseSetAsAction
{
public override string Label
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents action to set image as Windows desctop wallpaper.
/// </summary>
internal class SetAsWallpaperBackgroundAction : BaseSetAsAction
{
public override string Label
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@

namespace Files.App.Actions
{
/// <summary>
/// Represents base action to rotate image.
/// </summary>
internal abstract class BaseRotateAction : ObservableObject, IAction
{
private readonly IContentPageContext context;
Expand Down
Loading