StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

PO
text
Body
copied!<p>Info I've been able to gather since posting this question confirms that even though <code>csc /doc:</code> will accept either format, the single-line format has some advantages over the multi-line format:</p> <p>1) 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 <code>/</code> three times you will see a context-specific template generated for you like this:</p> <blockquote> <pre><code> /// <summary> /// /// </summary> /// <param name="arg1"></param> /// <param name="arg2"></param> /// <returns></returns> </code></pre> </blockquote> <p>This doesn't work if you position the cursor on the method and press <code>/</code>,<code>*</code>,<code>*</code>.</p> <p>2) 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. </p> <p>3) 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.</p> <p>4) 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:</p> <blockquote> <pre><code> /** * <thiscutetag>some info</thiscutetag> */ /** * <theothercutetag>more info</theothercutetag> */ public static void Main() { } </code></pre> </blockquote> <p>When 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:</p> <blockquote> <pre><code> /// <thiscutetag>some info</thiscutetag> /// <theothercutetag>more info</theothercutetag> public static void Main() { } </code></pre> </blockquote>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload