Документация XML: использование «cref» в <returns>это приемлемо или не нужно?

Question

Я использую GhostDoc для документирования своих методов и т. Д. И он работает хорошо, но он не заполняет <returns> ...

Может кто-нибудь сказать мне, что я должен делать, например

Если он возвращает объект с именем "Roles", то

<returns>A role object see <see cref = "UserRole" /></returns>

или просто

<returns>A role object</returns>

или

<returns>A role</returns>

Я немного знаю его звукиБудучи слишком точным, но я хочу начать с правильного: -)

Возьмем, например, стандартный тип возврата строки имени пользователя

<returns>The user name</returns>

<returns>The user name, see <see cref = "system.string" /> </returns>

Answer 1

Принимая ваши реплики из MSDN ( пример 1 , пример 2 ):

<returns>A <see cref="string" /> that contains the username</returns>

<returns>An object that contains role information</returns>

Генератор документации будет включать в себя тип возвращаемого значения, поэтомунет необходимости всегда включать его;однако, если это имеет смысл (или вы хотите указать на это), это не проблема, но, скорее всего, в потоке оператора, а не в виде отдельного оператора «см. X».