سؤال

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;
هل كانت مفيدة؟

المحلول

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.

نصائح أخرى

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.

مرخصة بموجب: CC-BY-SA مع الإسناد
لا تنتمي إلى StackOverflow
scroll top