Компилирование документирующих комментариев
Для получения XML-файла, содержащего документирующие комментарии, достаточно указать параметр /doc в командной строке компилятора. Например, для компилирования файла DocTest.cs, содержащего XML-комментарии, в командной строке необходимо ввести следующее.
Csc DocTest.cs /doc:DocTest.xml
Для вывода результата в XML-файл из интегрированной среды разработки Visual Studio необходимо активизировать окно Свойства (Properties) для текущего проекта. Затем следует выбрать свойство Построение (Build), установить флажок XML-файл документации (XML Documentation File) и указать имя выходного XML-файла.
Пример составления документации в формате XML
В приведенном ниже примере демонстрируется применение нескольких документирующих комментариев: как однострочных, так и многострочных. Любопытно, что многие программисты пользуются последовательным рядом однострочных документирующих комментариев вместо многострочных, даже если комментарий занимает насколько строк. Такой подход применяется и в ряде комментариев из данного примера. Его преимущество заключается в том, что он позволяет ясно обозначить каждую строку как часть длинного документирующего комментария. Но это все же, скорее, дело стиля, чем общепринятая практика составления документирующих комментариев.
// Пример составления документирующих комментариев,
using System;
/** <remark>
Это пример многострочного документирования в формате XML.
|
|
|
В классе Test демонстрируется ряд дескрипторов.
</remark>
*/
class Test {
///<summary>
Выполнение программы начинается с метода Main().
///</summary>
static void Main() {
int sum;
sum = Summation(5);
Console.WriteLine("Сумма последовательных чисел " +
5 + " равна " + sum);
}
///<summary>
Метод Summation() возвращает сумму его аргументов.
///<param name = "val" >
Суммируемое значение передается в качестве параметра val.
///</param>
///<see cref = "int" > </ see >
/// < returns >
Сумма возвращается в виде значения типа int.
///</returns>
/// </summary>
static int Summation(int val) {
int result = 0;
for (int i = 1; i <= val; i++)
result += i;
return result;
}
}
Если текст приведенной выше программы содержится в файле XmlTest.cs, то по следующей команде будет скомпилирована программа и получен файл XmlTest.xml, содержащий комментарии к ней.
Csc XmlTest.cs /doc:XmlTest.xml
После компилирования получается XML-файл, содержимое которого приведено ниже.
<?xml version="1.0"?>
<doc>
<assembly>
<name>Program</name>
</assembly>
<members>
<member name="T:Test">
<remark>
Это пример многострочного документирования в формате XML.
В классе Test демонстрируется ряд дескрипторов.
|
|
|
</remark>
</member>
<member name="M:Test.Main">
<summary>
Выполнение программы начинается с метода Main().
</summary>
</member>
<member name="M:Test.Summation(System.Int32)">
<summary>
Метод Summation() возвращает сумму его аргументов.
<param name="val">
Суммируемое значение передается в качестве параметра val.
</param>
<see cref="T:System.Int32"> </see>
<returns>
Сумма возвращается в виде значения типа int.
</returns>
</summary>
</member>
</members>
</doc>
Следует заметить, что каждому документируемому элементу присваивается уникальный идентификатор. Такие идентификаторы применяются в других программах, которые документируются в формате XML.
Предметный указатель
(Удален. Все-равно номеров страниц нет. См. Оригинал)
Спецификации
HERBERT SCHILDT ПОЛНОЕ РУКОВОДСТВО C# 4.0
Москва • Санкт-Петербург • Киев 2011
ББК 32.973.26-018.2.75 Ш 57 УДК 681.3.07
Издательский дом "Вильямс"
Зав. редакцией С.Н. Тригуб Перевод с английского и редакция И.В. Берштейна
По общим вопросам обращайтесь в Издательский дом "Вильямс" по адресу: info@williamspublishing.com, http://www.williamspublishing.com
Шилдт, Герберт.
Ш57 C# 4.0: полное руководство. : Пер. с англ. — М. : ООО "И.Д. Вильямс", 2011. — 1056 с.: ил. — Парал. тит. англ.
|
|
|
ISBN 978-5-8459-1684-6 (рус.)
ББК 32.973.26-018.2.75
Все названия программных продуктов являются зарегистрированными торговыми марками соответствующих фирм.
Никакая часть настоящего издания ни в каких целях не может быть воспроизведена в какой бы то ни было форме и какими бы то ни было средствами, будь то электронные или механические, включая фотокопирование и запись на магнитный носитель, если на это нет письменного разрешения издательства McGrow-Hill Higher Ed.
Authorized translation from the English language edition published by McGraw-Hill Companies, Copyright © 2010
All rights reserved. Except as permitted under the Copyright Act of 1976, no part of this publication may be reproduced or distributed in any form or by any means, or stored in a database or retrieval system, without the prior written permission of publisher, with the exception that the program listings may be entered, stored, and executed in a computer system, but they may not be reproduced for publication.
Russian language edition published by Williams Publishing House according to the Agreement with R&I Enterprises International, Copyright © 2011
Научно-популярное издание Герберт Шилдт C# 4.0: полное руководство
Литературный редактор Е.П. Перестюк
Верстка А.В. Чернокозинская Художественный редактор С А. Чернокозинский Корректор АЛ. Гордиенко
Подписано в печать 17.09.2010. Формат 70x100/16. Гарнитура Times. Печать офсетная.
Уел. печ. л. 85,14. Уч.-изд. л. 51,55.
|
|
|
Тираж 1500 экз. Заказ № 24007.
Отпечатано по технологии CtP в ОАО "Печатный двор" им. А. М. Горького 197110, Санкт-Петербург, Чкаловский пр., 15.
ООО "И. Д. Вильямс", 127055, г. Москва, ул. Лесная, д. 43, стр. 1
© Издательский дом "Вильямс", 2011 © by The McGraw-Hill Companies, 2010
ISBN 978-5-8459-1684-6 (рус.) ISBN 0-07-174116-Х (англ.)
Спасибо, что скачали книгу в бесплатной электронной библиотеке Royallib.com
Оставить отзыв о книге
Все книги автора
Дата добавления: 2019-02-12; просмотров: 209; Мы поможем в написании вашей работы! |
Мы поможем в написании ваших работ!