Method Comments

[robertlarkins]

What would be nice is for IO.Abstractions to display the corresponding method comments from System.IO; for example DirectoryInfoBase.FullName would display the same comment (Gets the full path of the directory or file) as DirectoryInfo.FullName, rather than not displaying anything at all.

Unfortunately I don't know if it is possible to automatically pull comments across (using something like the inherit tag), or if the comments would have to be added manually (with the risk of comments potentially changing between System.IO and IO.Abstractions).

[ericnewton76]

There could be a utility written to grab the comments from current System.IO (depending on the framework) and update the source. And one would probably spend same amount of time roughly as just manually copying them over. Do as many as you can stomach and send a pull request! Would be appreciated =D

…

On Wed, Oct 11, 2017 at 4:59 PM, ayb4btu ***@***.***> wrote: What would be nice is for IO.Abstractions to display the corresponding method comments from System.IO; for example DirectoryInfoBase.FullName would display the same comment (*Gets the full path of the directory or file*) as DirectoryInfo.FullName, rather than not displaying anything at all. Unfortunately I don't know if it is possible to automatically pull comments across (using something like the inherit tag), or if the comments would have to be added manually (with the risk of comments potentially changing between System.IO and IO.Abstractions). — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#245>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACG_zK5BvMUujOfMD9VeDZslf8__b5Lqks5srSw-gaJpZM4P2Hjh> .

-- E.Newton Senior Software Craftsman Cell: 407-497-1429 EMail: ericnewton76@gmail.com

[robertlarkins]

I'll take a look into it. A concern I have though is the possibility of the System.IO comments changing and IO.Abstractions having outdated comments, though I suppose I could assume the System.IO comments are unlikely to change.
Also, any idea what is happening with IO.Abstractions? As there is a number of pull requests sitting there already.

[robertlarkins]

@jpreese @ericnewton76 I've started looking at adding method comments. I'm using System.IO.FileSystem.xml for this, and can be found here (depending on .Net Core version):
Program Files\dotnet\sdk\NuGetFallbackFolder\microsoft.netcore.app\2.1.1\ref\netcoreapp2.1\System.IO.FileSystem.xml

I considered doing this as a tool to modify the .cs files directly, but opted for the manual approach. With respect to this, what's your thoughts on what should be included (I'm thinking the second approach)? If we use DirectoryBase.CreateDirectory(string path) as an example, should it be:

The minimal version:

/// <summary>
/// Creates all directories and subdirectories in the specified path unless they already exist.
/// </summary>
/// <param name="path">The directory to create.</param>
/// <returns>
/// An object that represents the directory at the specified path. This object is returned regardless of whether a directory at the specified path already exists.
/// </returns>

The following which just includes the source method via inheritdoc (inheritdoc doesn't add anything to the comments as they are specified here).

/// <inheritdoc cref="Directory.CreateDirectory(string)"/>
/// <summary>
/// Creates all directories and subdirectories in the specified path unless they already exist.
/// </summary>
/// <param name="path">The directory to create.</param>
/// <returns>
/// An object that represents the directory at the specified path. This object is returned regardless of whether a directory at the specified path already exists.
/// </returns>

or include all tags:

/// <inheritdoc cref="Directory.CreateDirectory(string)"/>
/// <summary>
/// Creates all directories and subdirectories in the specified path unless they already exist.
/// </summary>
/// <param name="path">The directory to create.</param>
/// <returns>
/// An object that represents the directory at the specified path. This object is returned regardless of whether a directory at the specified path already exists.
/// </returns>
/// <exception cref="T:System.IO.IOException">The directory specified by <paramref name="path">path</paramref> is a file.  
/// -or-  
/// The network name is not known.</exception>
/// <exception cref="T:System.UnauthorizedAccessException"> The caller does not have the required permission.</exception>
/// <exception cref="T:System.ArgumentException"><paramref name="path"> path </paramref> is a zero - length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the <see cref="System.IO.Path.GetInvalidPathChars"></see> method.
/// -or-  
///<paramref name = "path">path</paramref> is prefixed with, or contains, only a colon character(:).</exception>
///<exception cref="T:System.ArgumentNullException"><paramref name="path">path</paramref> is null.</exception>
///<exception cref="T:System.IO.PathTooLongException">The specified path, file name, or both exceed the system-defined maximum length.For example, on Windows-based platforms, paths must be less than 248 characters and file names must be less than 260 characters.</exception>
///<exception cref="T:System.IO.DirectoryNotFoundException">The specified path is invalid(for example, it is on an unmapped drive).</exception>
///<exception cref="T:System.NotSupportedException"><paramref name="path">path</paramref> contains a colon character(:) that is not part of a drive label(&amp; quot;C:\&amp;quot;).</exception>

[jpreese]

I'm not super familiar with what inheritdoc brings to the table. I was under the impression it would pull up comments from the base class so we're not copy pasting the same documentation everywhere thats already provided in System.IO -- but it looks like in examples 2 and 3 we're still typing out all of the comments anyway.

So to put another way, whats the difference between approach one and two? (3 seems incredibly bloated to me)

[robertlarkins]

That's pretty much what it does, but visual studio doesn't have the inheritdoc functionality built into it to use the inheritdoc tag directly with intellisense:
https://visualstudio.uservoice.com/forums/121579-visual-studio-ide/suggestions/3745102-add-intellisense-support-for-the-inheritdoc-ta

I was thinking the second approach would provide both the comments and a link between the Abstraction methods and their concrete implementations. But on further investigation, we could just put in the inheritdoc tags and use the tools from https://www.inheritdoc.io/ to generate the comments in the .xml markdown files. That way, if or when visual studio updates inheritdoc, nothing needs to change. The only problem is having to run inheritdoc on the build before publishing to nuget.

[robertlarkins]

@jpreese I should have asked if going down the path of just using inheritdoc, and whether converting the xml markdown before deploying to nuget is a suitable option (for whoever does it)?

[fgreinacher]

We’re deploying through appveyor CI. If the preprocessing can be done there I’d be cool with that.

[robertlarkins]

I'm not familiar with how appveyor works, but I would assume that if InheritDoc Command Line Tool was installed to the solution then appveyor could run that .exe as part of its build process. Would need somebody familiar with appveyor to comment.

[fgreinacher]

Well, nothing fancy, the AppVeyor build is configured via appveyor.yml. There is excessive documentation at https://www.appveyor.com/docs/appveyor-yml/.

I think you could define a build step that invokes the tool before building the NuGet package.

[robertlarkins]

The Inheritdoc library currently doesn't accommodate System.*, so until it gets updated I'll get the inheritdoc tags in. At least this will allow tools (ReSharper) that handle inheritdoc tags to display the method comments.