weixin_39624461
weixin_39624461
2020-12-31 02:05

Method Comments

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).

该提问来源于开源项目:System-IO-Abstractions/System.IO.Abstractions

  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享
  • 邀请回答

14条回答

  • weixin_39624461 weixin_39624461 4月前

    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)?

    点赞 评论 复制链接分享
  • weixin_39790102 weixin_39790102 4月前

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

    点赞 评论 复制链接分享
  • weixin_39624461 weixin_39624461 4月前

    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.

    点赞 评论 复制链接分享
  • weixin_39790102 weixin_39790102 4月前

    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.

    点赞 评论 复制链接分享
  • weixin_39624461 weixin_39624461 4月前

    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.

    点赞 评论 复制链接分享
  • weixin_39790102 weixin_39790102 4月前

    Reopening to track the tool integration here

    点赞 评论 复制链接分享
  • weixin_39624461 weixin_39624461 4月前

    The xml documentation isn't being generated for either the netstandard1.4 nor netstandard2.0 system.io.abstractions.dll (it is for net40). I'm wondering if it is related to the project build targeting mentioned for issue #334?

    UPDATE: With Pull Request #336 this is now working.

    点赞 评论 复制链接分享
  • weixin_39624461 weixin_39624461 4月前

    I've been unsure how to modify the appveyor.yml file to use the inheritdoc tool so I've posted a question on the appveyor forums: https://help.appveyor.com/discussions/questions/23338-call-exe-in-nuget-package-while-accessing-mscorlibxml

    点赞 评论 复制链接分享
  • weixin_39790102 weixin_39790102 4月前

    All done with e8d8e72

    点赞 评论 复制链接分享
  • weixin_39562234 weixin_39562234 4月前

    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 https://github.com/tathamoddie/System.IO.Abstractions/issues/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.com

    点赞 评论 复制链接分享
  • weixin_39624461 weixin_39624461 4月前

    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.

    点赞 评论 复制链接分享
  • weixin_39624461 weixin_39624461 4月前

    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:

    c#
    /// <summary>
    /// Creates all directories and subdirectories in the specified path unless they already exist.
    /// </summary>
    /// <param name="path">The directory to create.
    /// <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).

    c#
    /// <inheritdoc cref="Directory.CreateDirectory(string)"></inheritdoc>
    /// <summary>
    /// Creates all directories and subdirectories in the specified path unless they already exist.
    /// </summary>
    /// <param name="path">The directory to create.
    /// <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:

    c#
    /// <inheritdoc cref="Directory.CreateDirectory(string)"></inheritdoc>
    /// <summary>
    /// Creates all directories and subdirectories in the specified path unless they already exist.
    /// </summary>
    /// <param name="path">The directory to create.
    /// <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(& quot;C:\&quot;).</exception>
    
    点赞 评论 复制链接分享
  • weixin_39827905 weixin_39827905 4月前

    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)

    点赞 评论 复制链接分享
  • weixin_39624461 weixin_39624461 4月前

    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.

    点赞 评论 复制链接分享

相关推荐