Есть ли стандарт (например, phpdoc или строка документации python) для комментирования кода C #?

Question

Существует ли стандартное соглашение (например, phpdoc или строка документации python) для комментирования кода C #, чтобы документация класса могла автоматически генерироваться из исходного кода?

Answer 1

Вы можете использовать комментарии в стиле XML и использовать инструменты для извлечения этих комментариев в документацию API.

Вот пример стиля комментария:

/// <summary>
/// Authenticates a user based on a username and password.
/// </summary>
/// <param name="username">The username.</param>
/// <param name="password">The password.</param>
/// <returns>
/// True, if authentication is successful, otherwise False.
/// </returns>
/// <remarks>
/// For use with local systems
/// </remarks>
public override bool Authenticate(string username, string password)

Некоторые элементы, облегчающие это:

GhostDoc , которые предоставляют единую комбинацию клавиш для автоматического создания комментариев для класса или метода. Sandcastle , который генерирует документацию в стиле MSDN из комментариев XML.

Answer 2

/// <summary>
///
/// </summary>
/// <param name="strFilePath"></param>

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

Answer 3

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

Answer 4

Microsoft использует « Комментарии к XML-документации », которая дает описания intellisense IDE, а также позволяет автоматически генерировать документацию в стиле MSDN с помощью такого инструмента, как Sandcastle, если вы включите создание файла XML выход.

Чтобы включить генерацию XML-файла для документации, щелкните правой кнопкой мыши проект в visual studio, нажмите «Свойства» и перейдите на вкладку «Сборка». Внизу вы можете указать место для вашего файла вывода XML-комментариев.

Answer 5

C # имеет встроенные команды документации Веселись!

Answer 6

Мне всегда говорили использовать блочные комментарии, открытые двумя или более звездочками, которые разделяют комментарии документации.

/**
Documentation goes here.
(flowerboxes optional) 
*/