Комментарии XML - должны ли ссылки на see быть полными?

Question

В принципе, когда действительно необходимо (если вообще необходимо) использовать полностью определенный 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 правильно связывать вещи, но необходимо ли, чтобы все было полностью квалифицировано?

---

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

Answer 1

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

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

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

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

Answer 2

Я не могу говорить на Sandcastle, но на основе моего опыта с другими инструментами E.g.Resjarper, похоже, что тип должен быть квалифицирован, если A) он не в неисправности или B) оно затенено другим типом, который более локально определен.

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

Answer 3

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

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