0

I am porting an application library from Java to C#. In the Java documentation, there are places that link to a particular code reference using custom text. For example:

Suffix --> {@link DataOutput#writeString String}

I tried using a similar approach in XML documentation comments...

Suffix --&gt; <see cref="DataOutput.WriteString(string)">String</see>

... but the whole link just vanishes from both Intellisense and the generated documentation when I try it that way. The question is, how do I construct similar code links with custom text using .NET XML documentation comments in C#? If there is no way to do it, what is the recommended workaround?

If it matters, we are experimenting with using the DocFx code generator.

NightOwl888
  • 55,572
  • 24
  • 139
  • 212
  • Have a look at SandCastle which is able to produce HTML-helpfiles (aside some others also) from your xml-docs. However VS isn´t able to handle links to other types or members as eclipse does for instance. – MakePeaceGreatAgain Jun 21 '17 at 08:12
  • DocFX supports such comments to generate a link. It's also used in its source code like [this](https://github.com/dotnet/docfx/blob/1a191f6f1853e48873d5f45003cda669d3df0cca/src/Microsoft.DocAsCode.Dfm/IDfmEngineCustomizer.cs#L11). Is the referenced method also built by DocFX? – Yuby Jun 25 '17 at 14:27
  • @Yuby - The link you referenced has a *standard code link* that uses the name of the code element as the link text (in this case `DfmEngineBuilder`). What I am asking about is making the link text into something other than the name of the code element that is referenced, such as `My Custom Text` (since it was done that way in the code that is being ported). – NightOwl888 Jun 25 '17 at 17:03
  • Now I get your point. I'm afraid the tag doesn't support it. You need to use DocFX's [cross reference](http://dotnet.github.io/docfx/tutorial/links_and_cross_references.html#different-syntax-of-cross-reference) – Yuby Jun 26 '17 at 01:41

1 Answers1

0

You can use DocFX's cross reference syntax: [String](xref:DataOutput.WriteString(System.String)).

See: http://dotnet.github.io/docfx/tutorial/links_and_cross_references.html#different-syntax-of-cross-reference

Yuby
  • 808
  • 7
  • 19