SubMain GhostDoc

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 создает очень хорошие заготовки документации, которые иногда нет необходимости исправлять. В результате – хорошая экономия времени. Рекомендуется к использованию.

Комментарии (1) -

мегополезная фича в условиях кодинг стандартов, регламентирующих наличие документации.

Добавить комментарий