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

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

24 голосов
/ 13 мая 2011

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

Ответы [ 3 ]

16 голосов
/ 16 мая 2011

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

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

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

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

3 голосов
/ 13 мая 2011

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

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

3 голосов
/ 13 мая 2011

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

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

...