How to write "XML doc" for declaration with multiple variables?

Question

Working on a fairly large C# project which is getting way to manny simmilar variables so lets say i have a piece like this

    double
        TempAngle = 1,
        AngleCountDown = HalfSight,
        SightAngleFromCopter = 0;

how do i document them like i do methods (see below)?

    /// <summary>
    /// general explanation
    /// </summary>
    /// <param name="a">some hole num</param>
    /// <param name="b">some string</param>
    public MainWindow( int a ,string b)
    {}

In the end what i whould like to do is to write something like

    /// <param name="TempAngle">some</param>
    /// <param name="AngleCountDown">something</param>
    /// <param name="SightAngleFromCopter">something else</param>
    double
        TempAngle = 1,
        AngleCountDown = HalfSight,
        SightAngleFromCopter = 0;

If your code is clear enough, including your variable names, then you won't need to document them. — John Saunders, Mar 20 '13 at 01:31
If you have such a large code base that you aren't sure what your code is doing, then this a certain sign that it's time to refactor. Consider cleaning up your code and breaking it into small, clear, well-defined classes that serve a specific purpose. — David L, Mar 20 '13 at 01:32
If they are member variables, just "fix" the format so there is one per line. Then just use a normal
. — , Mar 20 '13 at 01:38
possible duplicate of [How to write comments / documentation for variables / fields / lists in VS 2010?](http://stackoverflow.com/questions/7954029/how-to-write-comments-documentation-for-variables-fields-lists-in-vs-2010) — Nikhil Agrawal, Mar 20 '13 at 01:42
ok from the top. The code is fairly clear and i don't have the time (Scientific research, proof of concept simulation project), but i would like to add some more detailed information on the variables. I know refactoring is the usual way but time does not allow for it. To split it and use the
is as i know a solution but i would like it on the format i stated. Scope wise i whould like it to work in any scope. — Thomas Andreè Wang, Mar 20 '13 at 01:46
Noits not a duplicate, i read that before i asked, and those "solutions" did not work in my case — Thomas Andreè Wang, Mar 20 '13 at 01:47
i just copy pasted because i have no idea what i should write. That's kind of why i asked — Thomas Andreè Wang, Mar 20 '13 at 01:49
hmm just feels that there should exist some thing else maybe a variable tag or something like it — Thomas Andreè Wang, Mar 20 '13 at 01:52

score 5 · Accepted Answer · answered Mar 20 '13 at 01:46

5

You have to write for each variable like this

/// <summary>
/// general explanation for TempAngle
/// </summary>    
double TempAngle = 1;

/// <summary>
/// general explanation for AngleCountDown 
/// </summary>
double AngleCountDown = HalfSight;

/// <summary>
/// general explanation for sightanglefromcopter
/// </summary>
double SightAngleFromCopter = 0;

More over this will only work for class level variables and not for method level variables.

answered Mar 20 '13 at 01:46

Nikhil Agrawal

47,018
22
121
208

1

that just feels wrong, ugly and bloaty. it just feels like it should be possible. – Thomas Andreè Wang Mar 20 '13 at 01:51
param wont work here coz they are not params. Yeah it looks ugly but summary for each variable has to follow immediately before that. No code in between them. – Nikhil Agrawal Mar 20 '13 at 01:52
well ok you'll get you're check mark, I guess you earned it, hehe. – Thomas Andreè Wang Mar 20 '13 at 01:54
2

@ThomasAndreèLian The way you heap the variables together looks ugly to me. And also, the C# convention is to start variables (local variables and fields) with a lowercase letter. Both are just a matter of taste. – Daniel A.A. Pelsmaeker Mar 20 '13 at 01:55
thats true, when i work i write global variables all over the class, and then before i stop for the day i heap them. It's just a small quirk hehe everyone have their own style. – Thomas Andreè Wang Mar 20 '13 at 01:57

Jeff Mercado · Answer 2 · 2019-05-09T17:46:24.127

The Language Specification tells you where XML comments should appear and what they apply to.

Documentation Comments §19.1 (emphasis mine)

Comments having a special form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. Such comments are single-line comments that start with three slashes (///), or delimited comments that start with a slash and two stars (/**). They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method) that they annotate. Attribute sections (Attribute specification) are considered part of declarations, so documentation comments must precede attributes applied to a type or member.

In your case, you are documenting the declaration statement for those fields. If there happens to be multiple variable declarations within that statement, you can't pick out for what variables your documentation applies to, that's just not how it was designed to work.

The only reason why it appears that way for method declarations/definitions is that the parameters are part of what defines that method, they are not separate distinct elements.

I disagree with your assessment of it being "ugly and bloaty," declaring multiple variables in a single statement are a convenience to save some keystrokes. The moment you need to do different things to any of those variables (such as applying different modifiers or simply documenting them), they must be separated.

How to write "XML doc" for declaration with multiple variables?

2 Answers2