Комментарии XML - Должны ли ссылки быть полностью квалифицированными?

В принципе, когда действительно необходимо (если вообще) использовать полнофункциональный xml, см. ссылку:

<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2

Также, как насчет ссылок на объекты .NET Framework?

<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2

Я понимаю, что полностью квалифицированные элементы всегда позволят Microsoft Sandcastle правильно связывать вещи, но необходимо ли для того, чтобы все было полностью квалифицировано?

Sidenote: сможет ли Microsoft Sandcastle ссылаться на файлы справки .NET Framework или я трачу свое время, ссылаясь на <see cref="T:System.Collections.Generic.ICollection{T}"/>?

ОТВЕТЫ

Ответ 1

Оба Джозеф и Бен касаются полезных точек, но я думаю, что мой недавний опыт Sandcastle может быть полезен:

  • Когда вы компилируете свой проект, Visual Studio, как правило, сразу сообщит вам, действительно ли ваша ссылка действительна, выпуская предупреждение, если оно не может разрешить ссылку в ваших комментариях к доктору, будь то ссылка на ваши собственные типы или типы систем (и VS выполняет ваши "использования" ).

  • В сценарии наличия локального типа, маскирующего системный тип, необходимо учитывать два случая: ваша подпись однозначно квалифицирует ваш тип (охватываемый (1) выше), или ваша подпись точно дублирует тип системы. Последний случай требует явного значения, полностью определяя имя.

  • Вы коснулись использования явного указания префикса типа члена (например, "T: SuperWidget" ), но это более важно, чем большинство людей понимает: если вы используете тип члена prefix, тогда требуются полностью квалифицированные имена. Это фактически документировано в MSDN, но в очень мелкой печати - см. Обработка XML файла. И чтобы усугубить ситуацию, если вы опустите полное имя, вы не получите предупреждения во время сборки (!); просто никакая ссылка не генерируется в окончательном рендеринге Sandcastle. Существуют и другие проблемы, если вы явно указываете префикс типа члена - см. Раздел Разделение и устранение ссылок моей статьи о практических советах Sandcastle, Taming Sandcastle: Руководство программиста .NET для документирования вашего кода.

Ответ 2

Я не могу говорить за Sandcastle, но на основе моего опыта работы с другими инструментами, например. ReSharper, кажется, что тип должен быть квалифицирован, если a) он не находится в области видимости или b) он затенен другим типом, который более локально определен.

Другими словами, если вы using System.Collections.Generic, вам не нужно будет квалифицировать ICollection{T}. Однако, если вы случайно определили свой собственный интерфейс ICollection{T} в том же файле, вам придется квалифицировать первое (как и последнее, подумать об этом).

Ответ 3

Вы не тратите свое время в <see cref /> на платформу, на мой взгляд. Поставщик справки Visual Studio должен иметь возможность перехватывать и интерпретировать во время выполнения, когда вызов выполняется для этой справки. Я не использовал его недавно, но в прошлом он работал очень хорошо.

Что касается полной квалификации, она не нужна в большинстве сценариев, но зависит от ваших привычек, поскольку Бен упомянул. До тех пор, пока вы ссылаетесь на область действия (и должны быть, поскольку вы, вероятно, будете использовать ее, если вы ссылаетесь на нее, или вы должны добавить ее, чтобы ваш код не использовал полностью квалифицированную форму) просто тип должен быть достаточным.