Как вы создаете ссылки на код с пользовательским текстом ссылки в комментариях к документации?

Я переношу библиотеку приложений с Java на C#. В документации по Java есть места, которые ссылаются на конкретную ссылку на код, используя пользовательский текст. Например:

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

Я пытался использовать аналогичный подход в комментариях XML-документации...

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

... но вся ссылка просто исчезает как из Intellisense, так и из сгенерированной документации, когда я пытаюсь сделать это таким образом. Вопрос в том, как создать похожие ссылки на код с пользовательским текстом, используя комментарии к документации .NET XML в C#? Если нет способа сделать это, каков рекомендуемый обходной путь?

Если это важно, мы экспериментируем с генератором кода DocFx.


c# docfx documentation-generation xml-documentation
person NightOwl888    schedule 21.06.2017    source источник
comment
Взгляните на SandCastle, который может создавать HTML-файлы справки (помимо некоторых других) из ваших xml-документов. Однако VS не может обрабатывать ссылки на другие типы или элементы, как это делает, например, eclipse.   -  person HimBromBeere    schedule 21.06.2017
comment
DocFX поддерживает такие комментарии для создания ссылки. Он также используется в исходном коде, например это. Является ли упомянутый метод также созданным DocFX?   -  person Yuby    schedule 25.06.2017
comment
@Yuby. Ссылка, на которую вы ссылаетесь, имеет стандартную ссылку на код, в которой в качестве текста ссылки используется имя элемента кода (в данном случае DfmEngineBuilder). Я спрашиваю о том, чтобы сделать текст ссылки чем-то другим, кроме имени элемента кода, на который ссылаются, например My Custom Text (поскольку это было сделано таким образом в портируемом коде).   -  person NightOwl888    schedule 25.06.2017
comment
Теперь я понимаю вашу точку зрения. Боюсь, тег ‹see› не поддерживает это. Вам необходимо использовать перекрестную ссылку DocFX   -  person Yuby    schedule 26.06.2017

Ответы (1)


arrow_upward
0
arrow_downward

Вы можете использовать синтаксис перекрестных ссылок DocFX: [String](xref:DataOutput.WriteString(System.String)).

См.: http://dotnet.github.io/docfx/tutorial/links_and_cross_references.html#Different-syntax-of-cross-reference

person Yuby    schedule 18.07.2017
comment
или альтернативно: @"DataOutput.WriteString(System.String)?text=string" - person bitbonk; 04.08.2017