Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

C# XML /// Comments, where does <returns></returns> tag show up?

I am currently a programming student, and obviously my question is simple, but I haven't been able to find the answer to it online. So here it is:

In XML /// comments in C#, where does the <returns> tag show up, I know that everything contained in the <summary> tag shows up in intellisense when you hover your mouse over your method call, but not the returns tag.

So where does the <returns> tag come in?

Thanks.

like image 790
Alex Avatar asked Dec 04 '09 07:12

Alex


5 Answers

When you see the method in View >> Object Browser

For e.g. you will see something like this:

private int GetColumnIndex(Microsoft.Office.Interop.Excel.Worksheet worksheet, string columnName, int rowIndex, int startColumnIndex)
    Member of MyAddIn.CommandHandlers.CommandHandler

Summary:
Returns the column index with specified name and in specified row

Parameters:
worksheet: Target worksheet
columnName: Column name to find
rowIndex: Row index in which to search the column
startColumnIndex: Start index of the column

Returns:
The index of column if found, else returns 0
like image 132
A9S6 Avatar answered Oct 02 '22 23:10

A9S6


If you generate API documentation from the comments, it will show up in the Return value section, as seen here, right before the Remarks section.

like image 23
Fredrik Mörk Avatar answered Oct 02 '22 23:10

Fredrik Mörk


When you choose to build an XML documentation file on compilation, then everything that is contained in the XML documentation comments gets copied over into that file. Programs like Sandcastle then can build HTML documentation akin to the MSDN from that.

It doesn't show in Visual Studio's own IntelliSense, as far as I know. But that's no excuse not to write something there :-). ReSharper's Ctrl+Q for example does show it.

like image 25
Joey Avatar answered Oct 02 '22 23:10

Joey


For those that may come trying to find something. This might not be the best approach but IMHO it does make more understandable what a method does while hovering over the method name.

        /// <summary>
        /// Adds a new post given the mapped PostDTO and userId <br></br><br></br>
        /// <b>Returns</b> the newly created object, otherwise null.
        /// </summary>
        /// <param name="postDTO"></param>
        /// <param name="userId"></param>
        PostDTO addPost(PostDTO postDTO, long userId);

This way you can see something in VS (at least in VS 2019) like in next image, which in my experience, when trying to understand code made by others, at least you can tell what to expect, whether an actual object or null, or whatever scenario.

enter image description here

I hope it may be useful for others.

like image 27
Luis Mezas Avatar answered Sep 30 '22 23:09

Luis Mezas


The other sections (basically anything exception summary) won't appear in intellisense. They are only intended to appear in documentation generated from the XML, using a tool like Sandcastle.

like image 33
Richard Szalay Avatar answered Oct 04 '22 23:10

Richard Szalay