Как указать тип в комментарии XML <return>комментарий - PullRequest
Новая
       52

Как указать тип в комментарии XML <return>комментарий

6 голосов
/ 22 февраля 2012

В комментарии <return> моего комментария C # XML я хотел бы, чтобы выходные данные (я использую Sandcastle) указывали возвращаемый тип, но я не могу выяснить, как это сделать.

Псуэдо Пример: 

///<summary>
///Serves as a hash function for a particular type.
///</summary>
///<returns **Type="System.Int32"**>
///A hash code for the current Object.
///</returns>
public virtual int GetHashCode(){...}

Вышеприведенный пример - это пародия на то, что я думаю сказать Sandcastle, как указать тип возвращаемого значения, описанный в разделе Syntax документации - не так.

Для ясности, вот скриншот документации MSDN о методе GetHastCode () , который показывает тип возвращаемого значения, для которого я снимаю.

Нужно ли нам вручную указывать тип, или мы можем указать тип (аналогично примеру с макетом) и позволить Sandcastle определять, как отображать / форматировать вывод - аналогично тому, как Sandcastle автоматически отображает / форматирует тип для параметров через тег <param>.

enter image description here

Ответы [ 2 ]

4 голосов
/ 22 февраля 2012

Вам не нужно указывать это в документации XML - в конце концов, это было бы излишним, учитывая, что это в объявлении метода.

Я подозреваю, что это вопрос настройки стиля Sandcastle, если выдействительно хочешь - но ты находишь это особенно полезным?Это не значит, что пользователи не могут просто щелкнуть тип возврата в сигнатуре метода.(По крайней мере, так выглядит стиль прототипа в SHFB. См. Документацию Noda Time для примера того, как это выглядит.)

В MSDN, затем подпись метода не имеет ссылки (по крайней мере, не в Chrome; я не знаю, отличается ли это в IE), но лично я предпочел бы, чтобы это было в подписи вместо загроможденияактуальная документация.

2 голосов
/ 25 февраля 2012

Это сообщение (июль 2011 г.) содержит ответ Эрика Вудраффа (Автор SHFB) относительно отсутствия типа возврата, отображаемого в теге <return>:

Sandcastle не отображает информацию о типе для возвращаемой информации, и я не думаю, что это когда-либо было.При условии, что информация находится в информационном файле отражения, преобразования XSL могут быть изменены для ее отображения.У меня нет времени сейчас на это разбираться, но в какой-то момент я смогу выяснить, возможно ли это.

Полагаю, официальный ответ на мой ОП:Sandcastle не имеет автоматического способа указать тип возвращаемого значения, но, как уже упоминалось в Skeet, может быть возможным для этого путем изменения преобразований XSL.

...