SubMain GhostDoc это бесплатное дополнение для Visual Studio 2010, позволяющее экономить время при документировании кода. Используя правила и шаблоны, оно автоматически создает описания методов. В ряде случаев, результат даже не надо дорабатывать вручную.
Не буду вдаваться в описание, показывать вид окон настройки и т. д. Сразу перейду к демонстрации результатов работы GhostDoc. Вся документация в примерах, включая XML теги, была сгенерирована автоматически с настройками "из коробки".
Начнем с конструктора:
/// <summary>
/// Initializes a new instance of the <see cref="Blogroll"/> class.
/// </summary>
public Blogroll()
{
BlogRollItem.Saved += new EventHandler<SavedEventArgs>(BlogRollItem_Saved);
}
Полученное описание конструктора вполне стандартное. Подробности можно добавить по необходимости. Теперь посмотрим на методы с параметрами:
/// <summary>
/// Handles the Saved event of the BlogRollItem control.
/// </summary>
/// <param name="sender">The source of the event.</param>
/// <param name="e">The <see cref="BlogEngine.Core.SavedEventArgs"/> instance containing the event data.</param>
private void BlogRollItem_Saved(object sender, SavedEventArgs e)
{
}
/// <summary>
/// Gets the internet IP address using socket.
/// </summary>
/// <param name="internetHostName">Name of the internet host.</param>
/// <param name="port">The port.</param>
/// <returns></returns>
public static List<IPAddress> GetInternetIPAddressUsingSocket(string internetHostName, int port)
{
}
Оба результата – неплохие заготовки для дальнейшей работы. Причем, чем более осмысленные имена у методов и классов, тем лучше генерируемый текст. А вот возвращаемое значение надо полностью описывать вручную.
И в завершении, рассмотрим случай с переопределением метода. Базовый класс я решил выбрать случайным образом ...
public class DemoClass : Random
{
/// <summary>
/// Returns a random number within a specified range.
/// </summary>
/// <param name="minValue">The inclusive lower bound of the random number returned.</param>
/// <param name="maxValue">The exclusive upper bound of the random number returned. <paramref name="maxValue"/> must be greater than or equal to <paramref name="minValue"/>.</param>
/// <returns>
/// A 32-bit signed integer greater than or equal to <paramref name="minValue"/> and less than <paramref name="maxValue"/>; that is, the range of return values includes <paramref name="minValue"/> but not <paramref name="maxValue"/>. If <paramref name="minValue"/> equals <paramref name="maxValue"/>, <paramref name="minValue"/> is returned.
/// </returns>
/// <exception cref="T:System.ArgumentOutOfRangeException">
/// <paramref name="minValue"/> is greater than <paramref name="maxValue"/>.
/// </exception>
public new int Next(int minValue, int maxValue)
{
return 42;
}
}
В код добавлено описание, взятое у исходного метода. Наследование от классов ядра .NET не обязательно. Главное, чтобы у "родителя" была нужная документация.
Подведем итог. SubMain GhostDoc создает очень хорошие заготовки документации, которые иногда нет необходимости исправлять. В результате – хорошая экономия времени. Рекомендуется к использованию.