RC2: SA1623 incorrectly reported when using <para> tags

[qmfrederik]

SA1623 is raised for properties for which the documentation starts with a <para> tag.
This is on Visual Studio 2015 Update 1.

Repro:

Given the following code:

class Test
{
    /// <summary>
    /// <para>
    /// Gets or sets a value indicating whether SA1623 works with {para} tags.
    /// </para>
    /// </summary>
    public bool Property
    {
        get;
        set;
    }

    /// <summary>
    /// Gets or sets a value indicating whether SA1623 works with {para} tags.
    /// </summary>
    public bool Property2
    {
        get;
        set;
    }
}

The following error is reported:
SA1623 The property's documentation summary text must begin with: 'Gets or sets a value indicating whether'

[qmfrederik]

Seems to be related to #144 and #1806

[sharwell]

You shouldn't use <para> within a <summary> element. If your summary text is long enough to need multiple paragraphs, you should simplify the summary to a single sentence (which isn't wrapped in a <para> element) and move the remaining text to other elements, such as <remarks>, <example>, <returns>, or <value>.

I'm not sure we need to make any changes to SA1623, but I'm leaving the issue open for continued discussion.

[qmfrederik]

You shouldn't use <para> within a <summary> element.

I was surprised by this statement so I did some digging. Here's what I came up with:

<para> inside <summary> is valid because:

• StyleCop.Analyzers explicitely lists <para> inside <summary> in the description for SA1644
• Classic StyleCop does not report any warnings with the code examples from above. So at the least, StyleCop.Analyzers deviates from classic StyleCop and this should be marked as such
• The MSDN documentation for <summary> explicitely includes a <para> element in its sample.
• The SandCastle project also includes some classes where <para> is nested inside <summary>

<para> inside <summary> is not valid because:

• If your summary text is long enough to need multiple paragraphs, you should simplify the summary to a single sentence (which isn't wrapped in a element) and move the remaining text to other elements, such as , , , or .

Since classic StyleCop did mark this as valid, I would treat the "<para> inside <summary> is not valid" as a new rule all together, and have SA1623 focus on the actual text and ignore the tags.

My 2 cents.

[nbarbettini]

I would treat the "<para> inside <summary> is not valid" as a new rule all together, and have SA1623 focus on the actual text and ignore the tags.

👍 I like this solution.

[sharwell]

I'm marking this as an enhancement to essentially inline the text of a <para> element for the purpose of evaluating SA1608, SA1623, SA1624, SA1642, and SA1643.

@qmfrederik I'm not saying <para> is invalid within a <summary> element. I am simply recommending that you avoid them, as they are not necessary and arguably don't make sense in this context. SHFB definitely doesn't assume that the user included these, and in all the testing I did for the VS 2013 theme I wasn't using <para> elements in this context. That said, I don't think we need a rule to handle this. If a rule was implemented, it would probably be part of a separate project (which doesn't currently exist) like #601, #602, and #603.

[qmfrederik]

Hi @sharwell,

Sounds good to me!

Frederik.

[sharwell]

Actually this enhancement would apply to both so keeping it.