In Microsoft Visual C# 2010 Express, whenever I create a function, and use the 3 slashes to create the help code, I get something like this:
/// <summary>
/// Function to sum 2 numbers.
/// </summary>
/// <param name="foo">First number.</param>
/// <param name="bar">Second number.</param>
/// <returns>The sum of the numbers.</returns>
public int foobar( int foo, int bar )
{
return foo + bar;
}
I know that whenever I want to know what a function does, I can hover my mouse over it, and the tooltip shows the text written between the <summary>
tags.
Also, whenever I open the parentheses to write the parameters of the function I'm calling, I see the tooltip below the cursor which displays the text written between the <param name="foo">
tags.
So, my question is: Can I view the text written between the <returns>
tags without having to go to definition and view it in the code it's written in? And if so, how?
C# documentation comments use XML elements to define the structure of the output documentation. One consequence of this feature is that you can add any valid XML in your documentation comments. The C# compiler copies these elements into the output XML file.
The idea is that you get a summary in the intellisense tooltip, and can press F1 to show the full help, or F12 to jump to the declaration (which usually includes the documentation).
<param> Tag The <param> tag is used to describe parameters for a method or constructor. Let's say we have a method that adds two numbers together and returns the result as follows. 1 /// <param name="operand1">the left side operand.</
The first rule for commenting is it should have /// three slash for comments as C# supports C++ style commenting so commenting can be done by // -- two slashes -- but for Documentation /// is necessary. We will go through each one by one. You can add a paragraph to the description by using <para> tag.
You can view it in View >> Object Browser
.
Apart from this you do not see it anywhere else.
In case you would like to present the "return" information via a tooltip then it is better to put it inside the <summary>
itself as a part of the description.
There are some possibilities to make the <summary>
more readeable when you want to put more text inside, e.g. by using <para>
:
///<summary>
///<para>line1</para>
///<para>line2 (e.g. what a method returns)</para>
///</summary>
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With