Демонстрация: Созданиепростого wpf приложения
Solution: NET.CSharp.01
Project: WpfApplication
Урок 5:Документирование приложений
Урок знакомит с XML комментариями и возможностями их использования при разработке .NET приложений. В уроке описано создание файла в формате справки с помощью инструментаSandcastle.
Xml комментарии
В VisualStudio 2010 можно добавить комментарии к исходному коду, который будет обработан в файл XML. Комментарии могут быть использованыдля создания справочной документации по классу, а также для поддержки IntelliSense.Для того, чтобы система IntelliSense и компилятор документации могли понимать и обрабатывать комментарии, необходимо, чтобы они писались в соответствии с определенным форматом.
Первым признаком того, что комментарий является документационным, являются три слеша (///) в его начале. VisualStudio распознает по этому признаку документационный комментарий и автоматически генерирует для него соответствующую заготовку. После генерации заготовки разработчику достаточно лишь заполнить содержимое тегов и документационный комментарий готов. В следующем примере класс Helloсодержит теги документации<summary>и <seealso>.
///<summary>Класс Hello выводит на экран приветствие
///</summary>
publicclassHello
{
///<summary>Использованконсольныйввод-вывод. Длябольшейинформациио
///WriteLine<seealsocref="System.Console.WriteLine()"/>
///</summary>
publicstaticvoid Main()
{
Console.WriteLine("HelloWorld");
}
}
Встроенные комментарии являются частью стандарта Visual C#, в то время как XML комментарии это расширение Microsoft и, как правило, они используются средствами сторонних производителей, например, таких как SandcastleHelp File Builder.
http://go.microsoft.com/fwlink/?LinkId=192887
ОбщиетегиXmLкомментариев
Для документирования приложения существует несколько тегов XML, однако можно также создавать свои собственные пользовательские метки. В следующей таблице приведены XML-теги, используемые при работе с документационными комментариями, и их назначение:
Tег |
Назначение |
<c> |
Помечает текст как программный код. |
<exception> |
Документирует класс исключения. |
<summary> … </summary> |
Предоставляет краткое описание. Для более подробного описания используются теги <remarks>. |
<remarks> … </remarks> |
Содержит подробное описание. Этот тег может содержать вложенные разделы (пункты), списки и другие типы тегов. |
<example> … </example> |
Предоставляет пример того, как метод, свойство или другой член библиотеки должен быть использован. Этот тег часто связано с использованием вложенных тегов <code>. |
<code> … </code> |
Указывает, что прилагаемый текст является кодом приложения. |
<returns> … </returns> |
Документирует возвращаемое значение и тип метода. |
<include> |
Включает комментарии из другого файла документации. |
<list> |
Описывает список. |
<param> |
Задает описание передаваемого в метод аргумента. Имеет атрибут name, задающий имя аргумента. |
<paramref> |
Указывает, что слово является параметром метода. |
<permission> |
Документирует доступ к члену класса. |
<see> |
Предоставляет перекрестную ссылку на другой параметр. |
<seealso> |
Задает раздел «Смотри также». |
<value> |
Описывает свойство. |
Следует отметить, что если речь не идет о создании полноценной библиотеки классов, которуюпредполагается распространять как самостоятельный программный продукт и которуюнеобходимо снабдить максимально подробной помощью, сопоставимой по возможностям сMSDN, в использовании всех этих тегов нет необходимости. В повседневной жизниразработчику необходимо задавать лишь минимальное описание созданного импрограммного кода, для чего вполне достаточно ограничиться знанием тегов <summary> и<param>, отображаемых в качестве подсказок системой IntelliSense, а также тега <returns>,поскольку при задании описания для методов, возвращающих значение, он генерируетсяавтоматически и его содержимое отображается в Object Browser.
В теле программы документировать с использованием тегов <summary>, <param> и <returns>необходимо, как минимум:
все классы, структуры, перечисления и интерфейсы;
все не закрытые (private) поля, свойства и методы классов;
все элементы перечислений;
закрытые поля, свойства и методы в том случае, если тело класса имеет достаточнобольшой размер, или допускается хотя бы мысль о возможности его дальнейшей модификации.
При разработке коммерческих библиотекнеобходимо проводить полноценноедокументирование с использованием всего спектра тегов.Например, после следующего документированияклассаTriangle система IntelliSense начнет отображать документационныекомментарии в качестве подсказок (Рис. 8).
///<summary>
/// Класс, описывающий треугольник по трем сторонам
///</summary>
publicclassTriangle
{
privatedouble a;
privatedouble b;
privatedouble c;
///<summary>
///Конструктор
///</summary>
///<param name="a"></param>
///<param name="b"></param>
///<param name="c"></param>
public Triangle(double a, double b, double c)
{
this.a = a;
this.b = b;
this.c = c;
}
///<summary>
/// Определение площади треугольника по формуле Герона
///</summary>
///<returns>площадьтреугольника</returns>
publicdouble GetArea()
{
double p = (a + b + c) / 2;
double s = Math.Sqrt(p * (p - a) * (p - b) * (p - c));
return s;
}
}
Рис. 8.
Аналогично, при работе с объектом класса, для его методов и их аргументов также будутотображаться подсказки (Рис. 9).
Рис. 9.
http://go.microsoft.com/fwlink/?LinkId=192888