c# - C# : What are technical reasons to prefer///or/** 中的文档注释

Question

C# 语言规范的附录 A 处理文档注释，它指出有两种形式:

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

有偏好吗？我注意到人们更喜欢单行文档注释格式，但我不知道除了人们从美学角度选择之外是否还有技术或实际原因。

我还阅读了 Jones 和 Freeman 合着的“C# for Java Developers”一书，内容如下:

Code documentation comments are preceded by three forward slashes, as shown here:
/// A single line documentation comment.
The C# specification also recommends use of the familiar /** token to identify multiline documentation comments. However version 7.00 of the C# compiler does not support this syntax.

我无法验证最新版本的 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;
}

因此，重申一下，问题是哪种形式更可取，是否有技术或其他原因更喜欢上面示例中的 Method1 或上面示例中的 Method2 的文档注释样式？

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) 单行格式允许更清晰的文档注释布局，因为每一行都以相同的缩进开始， block 的所有行都可以使用，并且每行注释信息都是左对齐的。

3) 通常，使用单行样式的优点在于单行注释可以自由包含 */标记，而多行注释则不能；如果您在编辑器中将评论从一个地方复制/粘贴到另一个地方，它们通常更容易使用。

4) 如果您考虑 csc.exe 如何处理相邻的文档 block ，还有证据表明 C# 编译器更喜欢单行格式。考虑这样的声明:

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

当通过 csc/doc 传递时:将生成文档，就好像两个 block 的内容都修改了 Main 方法一样。这种行为并不直观，但如果将两个相邻的多行注释 block 转换为两个相邻的单行注释集，就会变得直观，如下所示:

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