<xref> references don't work from xmldoc comments

[defufna]

Operating System: (Windows or Linux or MacOS) Windows & Linux DocFX Version Used: 2.59.3.0 Template used: (default or statictoc or contain custom template) default Steps to Reproduce:

1. Clone https://github.com/defufna/XRefDemo
2. run dotnet build
3. go to doc subfolder
4. run docfx
5. open http://localhost:8080/api/XRefDemo.A.html

Expected Behavior: Summary for class A contains a self referencing link.

Actual Behavior: Summary for class A contains plain text link instead.

I suspect the problem is somewhere here https://github.com/dotnet/docfx/blob/662aa7da1b109d57c3bedf1a5a1dae9d6a71e86c/src/Microsoft.DocAsCode.Metadata.ManagedReference.Common/Parsers/TripleSlashCommentModel.cs#L877 Because when I remove .Replace("<", "&lt;") everything works. Not sure if this breaks something else.

[paulushub]

@defufna You are doing it wrong! Use the appropriate link format here and it will work.

namespace XRefDemo;

/// <summary>
/// <format type="text/markdown">
/// <![CDATA[
/// Info about [](xref:XRefDemo.A)
/// > [!NOTE]
/// > Test note
/// ]]>
/// </format>
/// </summary>
public class A
{
    /// <summary>
    /// Hello
    /// </summary>
    public void Test()
    {

    }
}

Moreover, please move to the DocFX way of documentation, the Sandcastle way of trying to hack everything into the the XML docs is not recommended. Use the overwrite feature to provide richer and more extensive docs, if you need one.

[defufna]

Thanks for replying so fast! Didn't know autolinks could work with that syntax, neat! Is there some sort of style guide about DocFX way of doing things? I mostly figured it out by looking at Microsoft's .NET/ASP.NET repos so that's probably how I ended with Sandcastle way of doing things...

[paulushub]

Is there some sort of style guide about DocFX way of doing things?

Unfortunately, there is no DocFX for the Sandcastle user guide I know of. Stuff like NamepaceDoc in Sandcastle are better done with overwrite, but the documentation of that feature does not point it out - you will only find out from closed issues here or Google search.

I have just created my first public documentation and trying to use that to learn more and hopefully provide the needed documentation improvements. https://elinamllc.github.io/SharpVectors/ You can continue to post issues here or in the Discussions forum, and I will do my best to share what I know with you.

[paulushub]

If you have time, also look at the Unity DocTools documentation, it uses DocFX. https://docs.unity3d.com/Packages/[email protected]/manual/index.html NOTE: I am not a Unity user/developer and cannot say more, only found it while searching for more information.