GhostPack / SharpUp

SharpUp is a C# port of various PowerUp functionality.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Suggestion: use XML documentation comments

knipp opened this issue · comments

commented

@HarmJ0y I think the code could benefit from using XML style comments instead of regular comments especially at the beginning of functions. This would give more meaningful IntelliSense hints when using the functions, and would allow for automatic documentation generation through Sandcastle.

https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments

I'd be willing to rework the existing comments into XML style comments and create a pull request for it, if you are interested. It would look more or less like this:

Before:
// checks if the current user has the specified AccessRight to the specified file or folder
// from https://stackoverflow.com/questions/1410127/c-sharp-test-if-user-has-write-access-to-a-folder/21996345#21996345

After:
/// <summary>
/// checks if the current user has the specified AccessRight to the specified file or folder
/// </summary>
/// <see cref="https://stackoverflow.com/questions/1410127/c-sharp-test-if-user-has-write-access-to-a-folder/21996345#21996345"/>
/// <param name="Path">Path to check access for</param>
/// <param name="AccessRight">The specific permission to check</param>
/// <returns>true if access is allowed, false otherwise</returns>

Good idea, my C# n00bness is showing :) I'll definitely check this out