В приведенном ниже примере демонстрируется применение нескольких документирующих комментариев: как однострочных, так и многострочных. Любопытно, что многие программисты пользуются последовательным рядом однострочных документирующих комментариев вместо многострочных, даже если комментарий занимает насколько строк. Такой подход применяется и в ряде комментариев из данного примера. Его преимущество заключается в том, что он позволяет ясно обозначить каждую строку как часть длинного документирующего комментария. Но это все же, скорее, дело стиля, чем общепринятая практика составления документирующих комментариев.

// Пример составления документирующих комментариев,

using System;

/**

Это пример многострочного документирования в формате XML.

В классе Test демонстрируется ряд дескрипторов.

*/

class Test {

  ///

  /// Выполнение программы начинается с метода Main().

  ///

  static void Main() {

    int sum;

    sum = Summation(5);

    Console.WriteLine("Сумма последовательных чисел " +

    5 + " равна " + sum);

  }

  ///

  /// Метод Summation() возвращает сумму его аргументов.

  ///

  /// Суммируемое значение передается в качестве параметра val.

  ///

  ///

  /// < returns >

  /// Сумма возвращается в виде значения типа int.

  ///

  ///

  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-файл, содержимое которого приведено ниже.

        Program

            Это пример многострочного документирования в формате XML.

            В классе Test демонстрируется ряд дескрипторов.

             Выполнение программы начинается с метода Main().

             Метод Summation() возвращает сумму его аргументов.

             Суммируемое значение передается в качестве параметра val.

             Сумма возвращается в виде значения типа int.

Следует заметить, что каждому документируемому элементу присваивается уникальный идентификатор. Такие идентификаторы применяются в других программах, которые документируются в формате 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: полное руководство

Литературный редактор Е.П. Перестюк