代码之家 › 专栏 › 技术社区 › Thomas Andreè Wang

如何为具有多个变量的声明编写“XML文档”?

xml-documentation documentation c#

Thomas Andreè Wang · 技术社区 · 12 年前

正在处理一个相当大的C#项目,该项目正在为manny simmilar变量让路,所以假设我有一篇这样的文章

    double
        TempAngle = 1,
        AngleCountDown = HalfSight,
        SightAngleFromCopter = 0;

我如何像记录方法一样记录它们(见下文)?

    /// <summary>
    /// general explanation
    /// </summary>
    /// <param name="a">some hole num</param>
    /// <param name="b">some string</param>
    public MainWindow( int a ,string b)
    {}

最后,我想做的是写一些这样的东西

    /// <param name="TempAngle">some</param>
    /// <param name="AngleCountDown">something</param>
    /// <param name="SightAngleFromCopter">something else</param>
    double
        TempAngle = 1,
        AngleCountDown = HalfSight,
        SightAngleFromCopter = 0;

2 回复 | 直到 12 年前

Nikhil Agrawal 12 年前

你必须像这样为每个变量写

/// <summary>
/// general explanation for TempAngle
/// </summary>    
double TempAngle = 1;

/// <summary>
/// general explanation for AngleCountDown 
/// </summary>
double AngleCountDown = HalfSight;

/// <summary>
/// general explanation for sightanglefromcopter
/// </summary>
double SightAngleFromCopter = 0;

以上内容只适用于类级别的变量,而不适用于方法级别的变量。

Jeff Mercado 5 年前

这个 Language Specification 告诉XML注释应该出现在哪里以及它们适用于什么。

文档注释 Â§19.1 (重点是我的)

具有特殊形式的注释可以用于指导工具从这些注释和它们前面的源代码元素生成XML。此类注释是以三个斜杠(///)开头的单行注释,或以斜杠和两个星号(/**)开头的分隔注释。 它们必须紧跟在它们注释的用户定义类型(如类、委托或接口)或成员(如字段、事件、属性或方法)之前。 属性节(属性规范)被视为声明的一部分,因此文档注释必须位于应用于类型或成员的属性之前。

在您的案例中,您正在记录这些字段的声明语句。如果该语句中恰好有多个变量声明,那么您就无法选择文档所应用的变量,这不是它的设计初衷。

方法声明/定义之所以如此,唯一的原因是参数是定义该方法的部分,它们不是单独的不同元素。

我不同意你对它“丑陋和膨胀”的评价,在一个语句中声明多个变量可以方便地保存一些击键。当你需要对这些变量中的任何一个做不同的事情(比如应用不同的修饰符或简单地记录它们)时,它们必须分开。

推荐文章

Alvaromon · 如何使用ReSharper获取C#样式的三斜杠注释++

6 年前

Shepmaster Tim Diekmann · 如何基于功能标志有条件地执行模块级doctest?

6 年前

depaulagu · react本机文档是如何制作的?

7 年前

yearntolearn · R包命名空间

7 年前

Jean-Baptiste Yunès · 如何在XCode中记录Swift函数的参数标签和非参数名称?

7 年前

Dimebag · dict的Python NumPy风格文档

7 年前

m00am · 如何对使用板条箱特性的函数进行doctest?

7 年前

zython Hiery Nomus · Aiohttp errno代码文档?Errno-2/111/113/104/101[关闭]

7 年前

userMod2 · 节点-遍历JS文件的文件夹并提取某些位[关闭]

7 年前

ian · ri中记录的关键字方法参数在哪里?[已关闭]

7 年前