代码之家  ›  专栏  ›  技术社区  ›  Sam

返回Visual Studio中文档注释中的标记

  •  1
  • Sam  · 技术社区  · 6 月前

    在the <returns>...</returns> 在我的方法的文档注释部分,我喜欢提供数据类型方法返回的详细信息。

    例如,一个返回 Customer ,我的文档注释可能如下:

    /// <summary>
    /// Basic description/explanation of what this method does...
    /// </summary>
    /// <param name="id"></param>
    /// <returns>Customer</returns>
    public async Task<Customer> DoSomethingAsync(Guid id)
    {
       // Method logic
       return myCustomer; // returning a Customer class
    }
    

    这工作得很好,但如果该方法返回,例如 List<Customer> returns 部分,我使用 <returns>List<Customer></returns> ,我收到一条警告,内容如下:

    XML注释的XML格式不正确--“需要元素的结束标记 “返回”

    我明白Visual Studio正在与 > 在里面 列表<客户> 。有什么建议可以让我在这种情况下仍然显示我的方法返回什么,或者我只是忽略这些警告吗?

    1 回复  |  直到 6 月前
        1
  •  2
  •   Moshe Katz    6 月前

    这个 documentation 解决了这个问题,说:

    对于通用的代码元素。, List<T> )无法使用,因为它生成无效的XML。可以使用支架代替支架(例如。; List{T} )或者可以使用XML转义语法(例如。, List&lt;T&gt; ).

    就我个人而言,我会在XML实体上使用大括号,这样更容易阅读,也更容易打字。