How to write comments / documentation for variables / fields / lists in VS 2010?

Question

There is

///<summary>
///This is summary for some class or method
///</summary>

documentation for classes or methods. But how to write this for simple variables or lists?

I use Visual Studio 2010 and when i hover over some list, property or what ever i would like to see some kind of summary (in that little tooltip) i have written to that specific thing.

///<doc>
///always use this list!
List<String> beer = new List<String>();

edit: ok, we have found out, that it works as usual as long u comment in your class but OUTSIDE a method or a function!!

Any way to document/comment within a method too?

public class BeerForall
{
    /// <summary>
    /// it works here
    /// </summary>
    public List<String> beer = new List<string>();

    public String giveBeer()
    {
        /// is not working, u can not comment
        /// <summary>
        /// test test, not working
        /// </summary>
        List<String> moreBeer = new List<string>();

        return "beer";
    }
}

It works fine for all properties and fields, won't probably work for any variable in a function? — gideon, Oct 31 '11 at 13:03
damn, you are right :/ does not work in a method. In a class u can document as usual, but within a method/function it does not work! Any way to make it work? — Gero, Oct 31 '11 at 13:08
Yes it does work for methods? Where is your method defined and where are you calling it from? If it shows in intellisense the comments will show. Might just take a few seconds to load sometime. — gideon, Oct 31 '11 at 13:10
What would be the purpose of documenting an implementation detail? — Rhys van der Waerden, Nov 11 '12 at 01:53

score 19 · Answer 1 · answered Oct 31 '11 at 17:13

19

As others mentioned, you can't get IntelliSense for local vars. However: If your function is so large that a "regular" comment is not close enough to read near the place where you're using the var, then the right fix is to refactor the function -- break it up into multiple, smaller methods, with fewer vars. I don't think this feature should exist, as it would serve only to facilitate writing excessively large functions.

answered Oct 31 '11 at 17:13

Craig Stuntz

125,891
12
252
273

3

Maybe you're not seeing how that could be useful. I suggest you take a look at doxygen. In doxygen, whatever documentation you can write in a comment before the function you can write also inside the function. That allows you to continue for instance the remarks section with an explanation of the algorithm, interleaving code and documentation in a style which is very close to literal programming. Some pieces of code benefit a lot. – migle Mar 28 '17 at 10:59
1

Refactoring code is good but I don't see how taking tools away from the programmer is a useful "feature" for enforcing good coding practices. FWIW I don't think it's working, whoever wrote the codebase I'm maintaining now did not say "oh gee, I can't comment local variables so that means I'm going to code better now". Also, hypothetically if this was really left out to encourage a good coding style, why do local variable Intellisense comments work for C/C++ but not C# in VS2013? – jrh May 02 '17 at 21:10
7

"I don't think this feature should exist, as it would serve only to facilitate writing excessively large functions." I think it should exists unless you can rewrite 30k+ lines of code of backend I have to deal with. – Maciej Szpakowski Sep 14 '17 at 15:50
5

We are actually documenting these variables in order to refactor the mega methods in the 1st place and the lack of this feature is not helping... – Zar Shardan Nov 08 '17 at 20:03
A bit late, but... If you're documenting them JUST for a refactor, rename them. Variables with 30+ character names are a bad fit for published code, but in the middle of a refactor they are just fine. – Sparr Oct 14 '22 at 20:57

gideon · Accepted Answer · 2011-10-31T15:53:20.453

13

Seems to work perfectly fine in Visual Studio 2010. I defined a List as a private field with a comment inside my MainForm class.

They won't work for local variables defined within functions though.

enter image description here

edited Oct 31 '11 at 15:53

answered Oct 31 '11 at 13:08

gideon

19,329
11
72
113

in the class itself it works. but try to document something within a method. see my edited first post – Gero Oct 31 '11 at 13:14
3

Yea thats what I said in my first comment to your question, you can't document variables defined within a method itself. – gideon Oct 31 '11 at 13:19
3

woudl be cool if could make it work for local method-level variables.. just so you could have intellisense for your local code. I mean, why not? – Brady Moritz Oct 20 '12 at 22:16

score 6 · Answer 3 · answered Oct 31 '11 at 13:12

6

As far as I know, adding comments for intellisense will not work for local variables declared within functions. If you were to make your local list an instance variable of the class, you would be able to do this.

answered Oct 31 '11 at 13:12

ooPeanutButter

433
2
9

user2587659 · Answer 4 · 2016-06-03T12:49:35.410

0

Edit: it looks like <var> is only supported for JavaScript.

As of Visual Studio 2012 you can add this documentation using the <var> element.

Here's Microsoft's documentation on it:
https://msdn.microsoft.com/en-us/library/hh542722(v=vs.110).aspx

edited Jun 03 '16 at 12:49

answered Apr 26 '16 at 21:34

user2587659

61
7

Unfortunately, the linked documentation only applies to Javascript. I tried using `` on a local variable as such, no effect. – John Weisz May 20 '16 at 13:31

score 0 · Answer 5 · answered Oct 31 '11 at 13:03

0

The same way as you write summary for classes and methods work for variables.

answered Oct 31 '11 at 13:03

Pedryk

1,643
1
13
28

abatishchev · Answer 6 · 2011-10-31T13:46:47.943

0

You can add such XML documentation comments to any class member, not inside a member (method, property, etc).

edited Oct 31 '11 at 13:46

answered Oct 31 '11 at 13:03

abatishchev

98,240
88
296
433

How to write comments / documentation for variables / fields / lists in VS 2010?

6 Answers6

Linked

Related