What's the proper way to comment a constructor in a generic class?

Question

What's the proper way to comment this?

/// <summary>
/// Initializes a new instance of the <see cref="Repository"/> class.
/// </summary>
/// <param name="unitOfWork">The unit of work.</param>
public Repository(IUnitOfWork unitOfWork)
{
    this.UnitOfWork = unitOfWork;
}

VS complains about it:

Warning 11 XML comment on 'Data.Repository.Repository(Data.IUnitOfWork)' has cref attribute 'Repository' that could not be resolved C:\Projects\xx\yy\DataAccess\Repository.cs 35 58 Data

score 52 · Accepted Answer · edited Sep 01 '20 at 14:11

52

You need to use curly braces:

/// <summary>
/// Initializes a new instance of the <see cref="Repository{T}"/> class.
/// </summary>

For each typeparam, just add an additional value in the braces, delimited with a comma.

edited Sep 01 '20 at 14:11

d219

2,707
5
31
36

answered Jul 29 '11 at 03:00

AnteSim

1,265
1
12
11

2

You can also use angled brackets as XML entities `<T>`. Of course, curly braces are much more convenient :) – BoltClock Jul 29 '11 at 03:02
2

BTW, "Initializes a new instance of the Repository class." (without tag) will be also OK for StyleCop. – Oleg Shuruev Jul 31 '11 at 19:41
Also, if you have multiple generic types, you can do something like this: `` – Alexander Nov 07 '13 at 16:37

score 5 · Answer 2 · answered Mar 13 '18 at 11:11

StyleCop has defined how it should look like.

If the class contains generic parameters, these can be annotated within the cref link using either of the following two formats:

/// <summary>
/// Initializes a new instance of the <see cref="Customer`1"/> class.
/// </summary>
public Customer()
{
}

/// <summary>
/// Initializes a new instance of the <see cref="Customer{T}"/> class.
/// </summary>
public Customer()
{
}

What's the proper way to comment a constructor in a generic class?

2 Answers2