C#中的文档注释:更喜欢///或/**的技术理由是什么

Question

C#语言规范的附录A涉及文档注释,它指出有两种形式:

single-line-doc-comment:
/// input-charactersopt
delimited-doc-comment:
/**delimited-comment-textopt*/

有偏好吗？我注意到倾向于选择单行文档评论格式,但我不知道除了人们从美学观点选择之外是否存在技术或实践原因.

我还在Jones和Freeman的"C#for Java Developers"一书中读到了以下内容:

代码文档注释前面有三个正斜杠,如下所示:
/// A single line documentation comment.
C#规范还建议使用熟悉的/**标记来标识多行文档注释.但是,C#编译器的7.00版本不支持此语法.

我一直无法验证csc的最新版本是否与多行语法不兼容.据我所知,这种语法运行得很好.

**edit**有人要求展示样品.这是样本:

/// <summary>
/// Performs a Method1 calculation on two strings
/// </summary>
/// <param name="arg1">The first string</param>
/// <param name="arg2">The second string</param>
/// <returns>The number 3</returns>
public static int Method1(String arg1, String arg2)
{
    return 3;
}
/**
 * <summary>
 * Performs a Method2 calculation on two strings
 * </summary>
 * <param name="arg1">The first string</param>
 * <param name="arg2">The second string</param>
 * <returns>The number 3</returns>
 */ 
public static int Method2(String arg1, String arg2)
{
    return 3;
}

所以重申的问题是哪种形式更可取,是否有技术或其他理由在上面的样本,上面的样本或上面的方法2中更喜欢方法1的文档评论样式？

Answer 1

自从发布此问题以来我已经能够收集的信息确认即使csc /doc:接受任一格式,单行格式也比多行格式有一些优势:

1)在Visual Studio中,IntelliSense将为您提供信息,说明您在键入时在方法调用表达式中传递的参数,无论您最初是使用///或/**记录方法.但是,只有在使用///格式时,Visual Studio才会使用预填充来编写文档注释.例如,如果将光标放在Visual Studio中的方法声明上方并按/三次,您将看到为您生成的特定于上下文的模板,如下所示:

    /// <summary>
    /// 
    /// </summary>
    /// <param name="arg1"></param>
    /// <param name="arg2"></param>
    /// <returns></returns>

如果定位在方法和按光标这不起作用/,*,*.

2)单行格式允许更清晰的文档注释布局,因为每行以相同的缩进开始,可以使用块的所有行,并且每行注释信息都是左对齐的.

3)一般来说,使用单行样式的优点在于,单行注释可以自由包含*/token而多行注释不是; 如果您在编辑器中将一段注释从一个地方复制/粘贴到另一个地方,它们通常更容易使用.

4)如果考虑csc.exe如何处理相邻的文档块,还有证据表明C#编译器支持单行格式.考虑这样的声明:

   /**
     * <thiscutetag>some info</thiscutetag>
     */
    /**
     * <theothercutetag>more info</theothercutetag>
     */
    public static void Main() { }

通过csc/doc时:将生成文档,就好像两个块的内容都修改了Main方法一样.此行为不直观,但如果将两个相邻的多行注释块转换为两个相邻的单行注释集,则会变得直观,如下所示:

    /// <thiscutetag>some info</thiscutetag>
    /// <theothercutetag>more info</theothercutetag>
    public static void Main() { }