Docs: Erroneously showing literal angle brackets?

Created on 4 Nov 2018  Â·  3Comments  Â·  Source: dotnet/docs

"If you want angle brackets to appear in the text of a documentation comment, use < and >, as shown in the following example."

Right now, as shown above, the documentation says that you can make angle brackets appear in a documentation comment by using literal angle brackets (< and >). Is this supposed to say that you can make angle brackets appear by using entities (the < entity and the > entity)? If I remember right, angle brackets are not supposed to appear in an XML document except as tag delimiters.


Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

Area - C# Guide P2

Most helpful comment

Yeah, I'm not sure. It doesn't seem to make sense to me. If you want brackets in the documentation, you use the HTML encoding such as &gt;

@BillWagner I can fix this up. I just want to make sure that changing the example is correct. I think it is. Putting < or > inside of the cref seems odd, since the syntax is { } for the overload and the cref attribute needs to resolve to something. I see this note as specifying that the COMMENT TEXT inside of the documentation nodes needs to be encoded.

All 3 comments

Yeah, I'm not sure. It doesn't seem to make sense to me. If you want brackets in the documentation, you use the HTML encoding such as &gt;

@BillWagner I can fix this up. I just want to make sure that changing the example is correct. I think it is. Putting < or > inside of the cref seems odd, since the syntax is { } for the overload and the cref attribute needs to resolve to something. I see this note as specifying that the COMMENT TEXT inside of the documentation nodes needs to be encoded.

I agree that this is simply a case of ampersand g t semicolon being passed and interpreted as a literal angle bracket in the documentation source.

@Thraka Your analysis is correct. Go ahead and make the fix.

Was this page helpful?
0 / 5 - 0 ratings

Related issues

sdmaclea picture sdmaclea  Â·  3Comments

mekomlusa picture mekomlusa  Â·  3Comments

LJ9999 picture LJ9999  Â·  3Comments

ite-klass picture ite-klass  Â·  3Comments

sime3000 picture sime3000  Â·  3Comments