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

 

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

 

XML-дескрипторы, распознаваемые компилятором, перечислены в следующей таблице:

 

Дескриптор	Описание
<c>	Помечает текст в строке как код
<code>	Помечает множество строк как код
<example>	Помечает пример кода
<exception>	Документирует класс исключения (синтаксис проверяется компилятором)
<include>	Включает комментарии из другого файла документации (синтаксис проверяется компилятором)
<list>	Вставляет список в документацию
<param>	Помечает параметр метода (синтаксис проверяется компилятором)
<paramref>	Указывает, что слово является параметром метода (синтаксис проверяется компилятором)
<permission>	Документирует доступ к члену (синтаксис проверяется компилятором)
<remarks>	Добавляет описание члена
<returns>	Документирует возвращаемое методом значение
<see>	Представляет перекрестную ссылку на другой параметр (синтаксис проверяется компилятором)
<seealso>	Представляет раздел «see also» («смотреть также») в описании (синтаксис проверяется компилятором)
<summary>	Представляет краткий итог о типе или члене
<value>	Описывает свойство

 

Как это работает? Пример:

 

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

 

namespace LC_Console

{

/// <summary>

/// Класс Program.

/// Основной класс программы,

/// выводящий текст "Hello, world!"

/// </summary>

class Program

{

/// <summary>

/// Класс First.

/// Дополнительный класс программы,

/// выводящий текст метода Second()

/// </summary>

class First

{

/// <summary>

/// Метод Second() является

/// входной точкой работы программы

/// </summary>

/// <param name="s">Аргумент метода Second()</param>

public void Second(string s)

{

Console.WriteLine(s);

}

 

public First() { }

}

 

/// <summary>

/// Метод Main() является

/// входной точкой работы программы

/// </summary>

/// <param name="args">Аргумент метода Main()</param>

static void Main(string[] args)

{

First F = new First();

// Форматируем шапку программы

Console.BackgroundColor = ConsoleColor.Green;

ConsoleColor Color = Console.ForegroundColor;

Console.ForegroundColor = ConsoleColor.Black;

Console.WriteLine("*******************************");

Console.WriteLine("**** Консольное приложение ****");

Console.WriteLine("*******************************\n");

// Основная программа

Console.BackgroundColor = ConsoleColor.Black;

Console.ForegroundColor = Color;

Console.WriteLine("Hello, world!"); // Вывод заданного текста в консоль

string s = "\nВторой метод";

F.Second(s);

Console.ReadKey(); // Ожидание нажатия клавиши пользователем

}

}

}

 

Теперь, при работе с чем-либо, что имеет XML-тэги, подсказки в этих самых тэгах будут отображаться при наведении мыши на этот объект (или при написании кода с этим объектом):

 

Рис. 3. 1. Отображение подсказки при применении метода Second

 

Компилятор С# может извлекать XML-элементы из специальных комментариев и использовать их для генерации файлов XML. Чтобы заставить компилятор сгенерировать XML-документацию для сборки, указывается опция /doc вместе с именем файла, который должен быть создан (Командная строка Visual Studio (2010), команда для компилятора csc.exe):

 

csc /t:library /doc:LC_Console.xml Program.cs

 

Данная команда сгенерирует файл XML по имени LC_Console.xml со следующим содержимым:

 

Рис. 3. 2. Содержимое XML-файла LC_Console.xml

 

Того же (вывода в файл) можно добиться пометив галочкой соответствующий вариант в (XML-файл документации) на вкладке «Построение» окна редактора свойств проекта в Visual Studio 2010.

 

Метод Main

 

Консольное приложение C# должно содержать метод Main, в котором начинается и заканчивается управление. В методе Main создаются объекты и выполняются другие методы.

Метод Main является статическим методом static, расположенным внутри класса или структуры. В предыдущем (консольное приложение) примере «Hello, world!» он расположен в классе с именем Program. Метод Main можно объявить одним из следующих способов:

 

static void Main()

{

//...

}

 

• Возвращает значение void.

 

static int Main()

{

//...

return 0;

}

 

· Также может возвращаться целое значение.

 

static void Main(string[] args)

{

//...

}

 

Или:

 

static int Main(string[] args)

{

//...

return 0;

}

 

· С обоими возвращаемыми типами он может принимать аргументы.

 

Параметры метода Main args являются массивом значений типа string, который содержит аргументы командной строки, используемые для вызова программы. В отличие от C++, массив не содержит имени исполняемого (EXE) файла.

 

Дополнительные сведения об использовании аргументов командной строки можно получить из примеров, приведённых в разделах Main() и аргументы командной строки (Руководство по программированию на C#) (http://msdn.microsoft.com/ru-ru/library/acy3edy3.aspx) и Практическое руководство. Создание и использование сборок с помощью командной строки (C# и Visual Basic) (http://msdn.microsoft.com/ru-ru/library/3707x96z.aspx).

 

Вызов метода ReadKey в конце метода Main предотвращает закрытие окна консоли, чтобы вывод при выполнении программы в отладочном режиме (компиляция в режиме Debug или Release в среде разработки Visual Studio 2010) можно было прочесть нажатием клавиши F5.

 

Разное

 

using System;

 

Эта строка означает, что в программе используется пространство имён System. В С# пространство имен определяет область объявлений. Благодаря пространству имён одно множество имен отделяется от других. По существу, имена, объявляемые в одном пространстве имен, не вступают в конфликт с именами, объявляемыми в другом пространстве имен. В анализируемой программе используется пространство имён System, которое зарезервировано для элементов, связанных с библиотекой классов среды.NET Framework, применяемой в С#. Ключевое слово using просто констатирует тот факт, что в программе используются имена в заданном пространстве имён. Попутно обратим внимание на весьма любопытную возможность создавать собственные пространства имён, что особенно полезно для работы, над крупными проектами.

 

Обратим внимание, что использование данной строки в программе не обязательно, т.к. в C# можно всегда полностью определить имя с помощью пространства имён, к которому оно принадлежит. Например, строку:

 

Console.ReadKey();

 

Можно переписать так:

 

System.Console.ReadKey();

 

Однако указывать пространство имён System всякий раз, когда используется член этого пространства, — довольно утомительное занятие, и поэтому большинство программистов на С# вводят директиву using System; в начале своих программ. Следует, однако, иметь в виду, что любое имя можно всегда определить, явно указав его пространство имён, если в этом есть необходимость.

 

namespace LC_Console

 

С помощью ключевого слова namespace объявляется пространство имён, с которым должен быть ассоциирован класс. Весь код в последующих фигурных скобках рассматривается как принадлежащий этому пространству имен. Оператор using специфицирует пространство имён, которое должен просматривать компилятор в поисках классов, упомянутых в коде, но не определенных в текущем пространстве имен. Это служит тем же целям, что оператор import в Java и using namespace в С++.

 

class Program

 

В этой строке ключевое слово class служит для объявления вновь определяемого класса. Класс является основной единицей инкапсуляции в С#, a Program — это имя класса. Определение класса начинается с открывающей фигурной скобки «{«и оканчивается закрывающей фигурной скобкой «}». Элементы, заключённые в эти фигурные скобки, являются членами класса. Не вдаваясь пока что в подробности, достаточно сказать, что в С# большая часть действий, выполняемых в программе, происходит именно в классе.

 

Метод Main, как уже говорилось, является точкой входа в программу. Формально класс, в котором определяется метод Main, называется объектом приложения. Хотя в одном исполняемом приложении допускается иметь более одного такого объекта (это может быть удобно при проведении модульного тестирования), при этом обязательно необходимо информировать компилятор о том, какой из методов Main должен использоваться в качестве входной точки. Для этого нужно либо указать опцию main в командной строке, либо выбрать соответствующий вариант в раскрывающемся списке (Автоматически запускаемый объект) на вкладке «Приложение» окна редактора свойств проекта в Visual Studio 2010.

Как уже говорилось выше, в сигнатуре метода Main присутствует ключевое слово static. Область действия статических (static) членов охватывает уровень всего класса (а не уровень отдельного объекта) и потому они могут вызываться без предварительного создания нового экземпляра класса.

Внутри метода Main используется несколько встроенных методов предопределенного класса Console, в частности BackgroundColor — задаёт цвет фона, ForegroundColor — задаёт цвет контента (в нашем случае текста).

 

Ввод и вывод

 

Программы на C#, как правило, используют службы ввода/вывода, предоставляемые библиотекой времени выполнения в .NET Framework. WriteLine — выводит на экран строку и ReadLine — считывает данные из консоли. Код Console.WriteLine("Hello, world!"); использует метод WriteLine. Это один из методов вывода класса Console в библиотеке времени выполнения. Он выводит свои строковые параметры в стандартном потоке вывода, за которым следует новая строка. Другие методы Console используются для разных операций ввода и вывода.

 

Дополнительные сведения о методах ввода/вывода можно получить в разделе System.IO (http://msdn.microsoft.com/ru-ru/library/system.io.aspx).

Общая структура программы

Общая структура программы на C#

 

Программа на языке C# может состоять из одного или нескольких файлов. Каждый файл может содержать ноль или более пространств имён. Пространство имён может включать такие элементы, как классы, структуры, интерфейсы, перечисления и делегаты, а также другие пространства имён. Ниже приведена скелетная структура программы C#, содержащая все указанные элементы:

 

// Скелет программы на C#

using System;

 

namespace YourNamespace // Пространство имён программы

{

class YourClass // Класс

{

}

 

struct YourStruct // Структура

{

}

 

interface IYourInterface // Интерфейс

{

}

 

delegate int YourDelegate(); // Делегат

 

enum YourEnum

{

}

 

namespace YourNestedNamespace // Дополнительные пространства имён

{

struct YourStruct

{

}

}

 

class YourMainClass

{

static void Main(string[] args)

{

// Какой-то код приложения

}

}

}

 

Дополнительные сведения о правилах написания кода можно получить в разделе Соглашения о написании кода на C# (Руководство по программированию на C#) (http://msdn.microsoft.com/ru-ru/library/ff926074.aspx).

Дополнительные сведения по самому языку можно получить в разделе Спецификация языка C# (http://msdn.microsoft.com/ru-ru/library/ms228593.aspx). Спецификация языка является предписывающим источником информации о синтаксисе и использовании языка C#.

Введение в систему типов