Комментарии 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}"/>?

24
c# fully-qualified-naming sandcastle xml-comments

3 ответов

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

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

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

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

16

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

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

3

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

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

3