Перейти к основному содержимому

Лабораторная работа №7. XML комментарии в C#.

Цель работы:​

Изучить механизм XML комментариев в языке программирования C# и научиться их использовать для создания качественной документации к коду.

Теоретическое введение:​

XML комментарии в C# позволяют разработчику документировать свой код непосредственно в исходных файлах. Эти комментарии структурированы в формате XML и могут быть использованы для автоматической генерации документации с помощью инструментов, таких как Sandcastle или встроенного в Visual Studio генератора документации.

Комментарии XML-документации

Рекомендуемые XML-теги для комментариев к документации по C#

Основные теги XML комментариев:

  1. <summary> — краткое описание метода, класса или свойства.
  2. <param> — описание параметра метода или функции. Имеет атрибут name, который указывает на имя параметра.
  3. <returns> — описание возвращаемого значения метода или функции.
  4. <remarks> — дополнительные замечания или пояснения.
  5. <example> — пример использования метода, класса или свойства.
  6. <exception> — описание исключения, которое может быть выброшено методом или функцией. Имеет атрибут cref для ссылки на тип исключения.
  7. <typeparam> — описание обобщённого параметра метода или класса.
  8. <see> и <seealso> — ссылки на другие члены или типы.

Пример простого использования XML комментариев:

/// <summary>
/// Класс для работы с банковскими счетами.
/// </summary>
public class BankAccount
{
    /// <summary>
    /// Баланс на счете.
    /// </summary>
    private decimal balance;

    /// <summary>
    /// Конструктор для создания нового банковского счета с начальным балансом.
    /// </summary>
    /// <param name="initialBalance">Начальный баланс.</param>
    public BankAccount(decimal initialBalance)
    {
        balance = initialBalance;
    }

    /// <summary>
    /// Метод для добавления суммы на счет.
    /// </summary>
    /// <param name="amount">Сумма для добавления.</param>
    public void Deposit(decimal amount)
    {
        balance += amount;
    }

    /// <summary>
    /// Метод для снятия суммы со счета.
    /// </summary>
    /// <param name="amount">Сумма для снятия.</param>
    /// <exception cref="InvalidOperationException">Выбрасывается, если на счете недостаточно средств.</exception>
    public void Withdraw(decimal amount)
    {
        if (amount > balance)
        {
            throw new InvalidOperationException("Недостаточно средств на счете.");
        }

        balance -= amount;
    }

    /// <summary>
    /// Получение текущего баланса.
    /// </summary>
    /// <returns>Текущий баланс на счете.</returns>
    public decimal GetBalance()
    {
        return balance;
    }
}

Оборудование и программное обеспечение:​

  • Среда разработки (например, Visual Studio или JetBrains Rider)
  • Установленный .NET SDK

Ход работы:​

  1. Создание проекта:

    • Откройте Visual Studio и создайте новый консольный проект на C#.
    • Назовите проект, например, XmlCommentsExample.

  2. Реализация простого класса с использованием XML комментариев:

    • Создайте класс BankAccount и добавьте к нему методы и свойства, используя XML комментарии, как показано в примере выше.

  3. Добавление более сложных комментариев:

    • Добавьте в класс метод, который выбрасывает несколько типов исключений. Например, метод перевода средств между счетами. Добавьте комментарии, которые документируют возможные исключения.
    • Добавьте примеры использования в комментариях к методам с помощью тега <example>.

  4. Компиляция и генерация документации:

    • В свойствах проекта включите опцию генерации XML документации. Это можно сделать через Проект -> Свойства -> Сборка -> Вывод документации.
    • Скомпилируйте проект и проверьте, что файл с расширением .xml был создан в папке с компилированными файлами.

  5. Просмотр и использование сгенерированной документации:

    • Откройте сгенерированный XML файл и изучите структуру сгенерированной документации.
    • Используйте Visual Studio, чтобы увидеть, как XML комментарии отображаются при использовании методов вашего класса. Наберите название метода в другом классе и посмотрите, как появляются подсказки с текстом из XML комментариев.

  6. Документирование обобщенного класса:

    • Создайте новый обобщенный класс, например, DataStore<T>, который может хранить список элементов любого типа.
    • Задокументируйте этот класс, используя теги <typeparam> и <typeparamref>.

Пример кода:

/// <summary>
/// Класс для хранения элементов любого типа.
/// </summary>
/// <typeparam name="T">Тип элементов, хранящихся в списке.</typeparam>
public class DataStore<T>
{
    private List<T> items = new List<T>();

    /// <summary>
    /// Добавляет элемент в хранилище.
    /// </summary>
    /// <param name="item">Элемент для добавления.</param>
    public void AddItem(T item)
    {
        items.Add(item);
    }

    /// <summary>
    /// Возвращает все элементы из хранилища.
    /// </summary>
    /// <returns>Список всех элементов.</returns>
    public List<T> GetAllItems()
    {
        return items;
    }
}

Индивидуальное задание​

Вариант 1: Документирование библиотеки математических функций​

Задание: Разработайте небольшую библиотеку математических функций, включающую методы для вычисления факториала, числа Фибоначчи, нахождения НОД и НОК двух чисел. Для каждого метода добавьте XML комментарии, включающие теги <summary>, <param>, <returns>, <remarks>, а также <example> с примером использования метода.

Дополнительное задание: Создайте метод для решения квадратного уравнения и задокументируйте возможные исключения, которые могут возникнуть, используя тег <exception>.

Вариант 2: Документирование класса работы с датами​

Задание: Создайте класс DateHelper, который содержит методы для вычисления количества дней между двумя датами, определения, является ли год високосным, и преобразования строки в объект DateTime. Для всех методов и параметров добавьте XML комментарии, включая примеры использования.

Дополнительное задание: Добавьте метод для форматирования даты в строку по разным форматам и задокументируйте его с помощью тегов <typeparam>, <typeparamref>, если метод будет обобщённым.

Вариант 3: Документирование системы учета студентов​

Задание: Разработайте класс Student, который содержит информацию о студенте (имя, возраст, номер студенческого билета). Создайте класс StudentDatabase для хранения списка студентов и методов добавления, удаления и поиска студента по номеру студенческого билета. Задокументируйте все классы и методы с использованием XML комментариев, включая примеры использования и возможные исключения.

Дополнительное задание: Добавьте метод для сортировки студентов по фамилии и задокументируйте его, добавив теги <remarks> для описания алгоритма сортировки.

Вариант 4: Документирование API для работы с файлами​

Задание: Создайте класс FileManager, который содержит методы для создания, удаления, копирования файлов, а также для чтения и записи данных в файл. Задокументируйте методы с помощью XML комментариев, описав параметры, возвращаемые значения и возможные исключения.

Дополнительное задание: Добавьте метод для асинхронного чтения файла и задокументируйте его, указав на необходимость использования async и await.

Вариант 5: Документирование игровой логики​

Задание: Разработайте класс GameCharacter, который содержит информацию о персонаже игры (имя, здоровье, уровень). Создайте класс Game, который управляет списком персонажей, позволяет добавлять новых персонажей, повышать их уровень и вычислять суммарное здоровье всех персонажей. Задокументируйте классы и методы с помощью XML комментариев, добавив примеры использования.

Дополнительное задание: Добавьте метод для сражения двух персонажей и задокументируйте возможные исходы с помощью тега <returns> и <remarks>.