1

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.

enter image description here

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

enter image description here

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

gunr2171
  • 16,104
  • 25
  • 61
  • 88
Jonathan Wood
  • 65,341
  • 71
  • 269
  • 466
  • 1
    It's also worth noting that this behavior also occurs if the class is not generic, and the property returned a fixed data type (such as string). – gunr2171 Oct 26 '22 at 18:17

1 Answers1

2

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

Populates Item.

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

}

enter image description here

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.

pfx
  • 20,323
  • 43
  • 37
  • 57
  • That's weird how the `P` prefix shows the right name but the name is not highlighted like normal property references. I'm pretty sure the issue I reported is confusing Visual Studio because of special handling for indexers. – Jonathan Wood Oct 26 '22 at 19:57