XML comments cannot correctly reference properties named 'Item'

Question

Given the following code:

class FixedWidthReader<T>
{
    public T? Item { get; private set; }

    /// <summary>
    /// Populates <see cref="Item"/>.
    /// </summary>
    public void Run()
    {

    }
}

The XML comments do not show the reference to Item correctly.

If I rename the Item property to anything else, say ItemX, it works fine.

Does anyone know why XML comments cannot correctly refer to a property called Item?

Answer 1

Defining it as <see cref="P:Item" /> shows

Populates Item.

/// <summary>
/// Populates <see cref="P:Item" />.
/// </summary>
public void Run()
{

}

The ID Strings section in the documentation shows the available prefixes, but for some reason any prefix character seems to give the same result when looking at it in Visual Studio.
(I'm using Visual Studio 2022.)

Maybe the correct usage of these is more important when using a document generation tool like DocFX or Sandcastle.

The table shows character P for member type Property.

This question shows more usages of these prefixes.

---

Update

When you configure Visual Studio to generate an XML documentation file in its output, you'll notice that also that ItemX property as in your example ends up as cref="P:FixedWidthReader`1.ItemX".

<member name="M:FixedWidthReader`1.Run">
    <summary>
    Populates <see cref="P:FixedWidthReader`1.ItemX"/>.
    </summary>
</member>

That generic format FixedWidthReader`1 looks to be the expected output, but for some reason Visual Studio has an issue in visualizing such a property when named Item, like you're suspecting.

I tend to say that making that change towards cref="P:Item" will break the actual type definition, just affecting the Visual Studio visualization.