Stylecopanalyzers: SA1619 "The documentation for type parameter 'T' is missing" conflicts with CS1710 for partial classes

Created on 15 Jul 2016  路  2Comments  路  Source: DotNetAnalyzers/StyleCopAnalyzers

Visual Studio 2015 14.0.25422.01 Update 3
StyleCopAnalyzers 1.0.0
Silverlight 5 project (but most probably an issue in other projects as well)
Output XML documentation enabled

Steps to reproduce:

  1. Create the following two files:

PersonFirstName.cs

    /// <summary>
    /// A person
    /// </summary>
    /// <typeparam name="T">The type</typeparam>
    public partial class Person<T>
    {
        /// <summary>
        /// Gets or sets the first name.
        /// </summary>
        /// <value>
        /// The first name.
        /// </value>
        public string FirstName { get; set; }
    }

PersonLastName.cs

    /// <summary>
    /// A person
    /// </summary>
    public partial class Person<T>
    {
        /// <summary>
        /// Gets or sets the last name.
        /// </summary>
        /// <value>
        /// The last name.
        /// </value>
        public string LastName { get; set; }
    }
  1. Build
    Notice the error SA1619 The documentation for type parameter 'T' is missing ... PersonLastName.cs.
  2. Add /// <typeparam name="T">The type</typeparam> to the Person class's documentation in PersonLastName.cs.
  3. Build
    Notice the error CS1710 XML comment has a duplicate typeparam tag for 'T' ... PersonLastName.cs.
bug wontfix

Most helpful comment

Interesting! On a side note...

:bulb: You shouldn't use the <summary> element twice. One of these two files should be using <content> instead of <summary>.

Marked as a :bug:. We should only report SA1619 on a partial class if the documentation comment contains a <summary> element. Files which use <content> are additional documentation of code only and do not need to duplicate the type parameter documentation.

All 2 comments

Interesting! On a side note...

:bulb: You shouldn't use the <summary> element twice. One of these two files should be using <content> instead of <summary>.

Marked as a :bug:. We should only report SA1619 on a partial class if the documentation comment contains a <summary> element. Files which use <content> are additional documentation of code only and do not need to duplicate the type parameter documentation.

It turns out the problem here was caused by the inclusion of duplicate <summary> elements for the type. Replacement of all but one of these elements will also resolve the CS1619 warning per the following:

https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/3d945bc3603dfa0fa2acf916def3fac45a9662c8/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1619GenericTypeParametersMustBeDocumentedPartialClass.cs#L158-L162

Was this page helpful?
0 / 5 - 0 ratings

Related issues

Onzi12 picture Onzi12  路  4Comments

RehanSaeed picture RehanSaeed  路  6Comments

iron9light picture iron9light  路  4Comments

arashk1368 picture arashk1368  路  4Comments

wmjordan picture wmjordan  路  6Comments