NickName:Mishax Ask DateTime:2013-09-04T11:56:43

Documentation comments in C#: What are technical reasons to prefer /// or /**

Appendix A of the C# language specification deals with documentation comments and it states that there are two forms:

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

is there a preference? I notice a tendency to prefer the single-line-doc-comment format but I do not know if there are technical or practical reasons besides people choosing from an aesthetic point of view.

I've also read in the book "C# for Java Developers" by Jones and Freeman the following:

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.

I've been unable to verify that the latest versions of the csc do not work with the multiline syntax. As far as I can tell this syntax works just fine.

**edit** Some people asked to show a sample. Here is the sample:

/// <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;
}

So the question, restated, is which form is preferable, are there technical or other reasons to prefer the documentation comment style of Method1 in the sample, above, or Method2 in the sample, above?

Copyright Notice：Content Author:「Mishax」，Reproduced under the CC 4.0 BY-SA copyright license with a link to the original source and this disclaimer.
Link to original article：https://stackoverflow.com/questions/18605146/documentation-comments-in-c-what-are-technical-reasons-to-prefer-or

Answers

Mishax 2013-09-04T05:26:25

Info I've been able to gather since posting this question confirms that even though csc /doc: will accept either format, the single-line format has some advantages over the multi-line format:\n\n1) In Visual Studio, IntelliSense will give you info clarifying the arguments you are passing in a method invocation expression as you are typing, regardless if you originally documented your method with /// or /**. However, Visual Studio will give you support in writing documentation comments using prefills only if you use the /// format. For example, if you place the cursor above a method declaration in Visual Studio and press / three times you will see a context-specific template generated for you like this:\n\n\n /// <summary>\n /// \n /// </summary>\n /// <param name=\"arg1\"></param>\n /// <param name=\"arg2\"></param>\n /// <returns></returns>\n\n\n\nThis doesn't work if you position the cursor on the method and press /,*,*.\n\n2) The single-line format allows a cleaner layout of the documentation comments since each line starts with the same indentation, all lines of the block can be used, and each line of comment information is left-aligned. \n\n3) There are, in general, advantages to using the single line style in that single line comments are free to contain the */ token whereas multiline comments are are not; and they are generally easier to work with if you are copying/pasting pieces of comments from one place to another inside an editor.\n\n4) There is also evidence that the C# compiler favors the single line format, if you consider how csc.exe deals with adjoined documentation blocks. Consider a declaration like this:\n\n\n /**\n * <thiscutetag>some info</thiscutetag>\n */\n /**\n * <theothercutetag>more info</theothercutetag>\n */\n public static void Main() { }\n\n\n\nWhen passing through csc /doc: the documentation will be generated as though the contents of both blocks modified the Main method. This behavior is not intuitive, but becomes intuitive if you transform the two adjoined multiline comment blocks into two adjoined sets of single-line comments, as follows:\n\n\n /// <thiscutetag>some info</thiscutetag>\n /// <theothercutetag>more info</theothercutetag>\n public static void Main() { }\n\n",