Таблица 31.2. Члены класса DocumentedClass

4. Щелкните в поле Summary (Краткая информация) метода GetFactors (), а затем на кнопке ... (многоточие). Измените текст в диалоговом окне Description (Описание), как показано на рис. 31.4 и в табл. 31.3.

Deecrtp*)n

Surnrnary

GetJ ttie f ectorj of a number.

Returns; Retumj a long array.

This method is used to obtain the factors of a number, thai IS. all the numbers that the number can be divided by without ieaving a remainder

If IncludeOne and IncludeSelf are both true and tht result returned consists Ot exactly two numbers tne number Itself and one) then the number is pnmej

I OK I I Cancel

Puc. 31.4. Диалоговое окно Description Таблица 31.3. Значения полей в диалоговом окне Description

Поле

Значение

Summary (Краткое описание)

Returns (Возвращаемые значения)

Remarks (Замечания)

Извлекает множители числа. Возвращает массив long.

Этот метод служит для получения множителей числа - т.е. всех чисел, на которые число может быть разделено без остатка. Если оба значения IncludeOne И IncludeSelf равны true, И результат состоит только из двух чисел (самого числа и единицы), число является простым.

5. Аналогично измените текст полей Value (Значение) и Remarks (Замечания) для свойств IncludeOne и IncludeSelf в соответствии с табл. 31.4.

Таблица 31.4. Значения полей Value и Remarks для свойств includeOne и includeSelf Свойство Текст поля Value Текст поля Remarks

IncludeOne Значение типа bool Если значение этого свойства установлено равным

true, результат long [ ] метода GetFactors () будет содержать 1.

IncludeSelf Значение типа bool Если значение этого свойства установлено равным

true, результат long [ ] метода GetFactors () будет содержать его параметр numberToFactor.

6. Щелкните на классе в диаграмме классов и измените поля Summary (Краткая информация) и Remarks (Замечания) класса в соответствии с табл. 31.5.

Таблица 31.5. Значения полей Summary и Remarks для класса Текст поля Summary Текст поля Remarks

Этот класс позволяет разлагать числа на Используйте метод GetFactor () для разложения множители в соответствии с определенны- числа на множители в соответствии с правилами правилами. ми, определенными свойствами includeOne и

IncludeSelf.

7. Просмотрите код класса DocumentedClass. Теперь он должен содержать добавленные XML-комментарии, как показано в следующем примере:

/ <8швтагу>

/ Извлекает множители числа. / </8Швтагу>

/ <гетаг]с8>Этот метод служит для получения множителей числа - т.е. всех / чисел, на которые число может быть разделено без остатка. / Если оба значения IncludeOne и IncludeSelf равны true, и результат / состоит только из двух чисел (самого числа и единихда) , число 51вляется / простым.</remar]cs>

/ <param name= numberToFactor >Число, которое нужно разложить на множители.</param> / <retums>Bo3Bpai4aeT массив long.</returns>

public long[] GetFactors(long numberToFactor) {

throw new System.NotlmplementedException0;

Описание полученных результатов

Этот пример демонстрирует использование диаграммы классов для определения XML-документацИи проекта. После прочтения предыдущего раздела может возникнуть вопрос, почему мы не добавили перекрестные ссылки между методами и тому подобными объектами. Например, почему текст Remarks для метода GetFactors () не был определен следующим образом:

Этот метод служит для получения множителей числа - т.е. всех чисел, на которые число может быть разделено без остатка.

Если оба значения <see cref= IncludeOne /> и <see cref= IncludeSelf /> равны <see langword= true />, и возвращенное значение состоит только из двух чисел (самого числа и единицы), число является простым.

Причина состоит в том, что текстовый редактор диаграммы класса автоматически пропускает текст, введенный в диалоговом окне Description, поэтому результат ввода выше приведенного кода в действительности будет выглядеть следующим образом:

/ <summary>

/ Извлекает множители числа. / </summary>

/ <гв1паг1с8>Этот метод служит для получения множителей числа - т.е. всех / чисел, на которые число может быть разделено без остатка. / Если оба значения &lt;see сге£= IncludeOne /&gt; / и &lt;see cref= IncludeSelf /&gt;

/ равны &lt;see langword= true /&gt;, и возвращенный результат состоит только / из двух чисел (самого числа и единихда) , число является простым.</remar]cs>

/ <param name= numberToFactor >Чиcлo, которое нужно разложить на множители.</рагат> / <returns>Bo3BpamaeT массив long.</returns> public long[] GetFactors(long numberToFactor) {

throw new System.NotlmplementedException0;

К сожалению, это одно из неудобств, с которым приходится мириться при добавлении XML-документации посредством диаграммы классов. Она прекрасно подходит для добавления текста, но для внедрения кода разметки XML-документации код приходится изменять вручную.

Генерирование файлов XML-документации

До сих пор вся добавляемая XML-документация была ограничена средой разработки во время работы с проектом. Если требуется действительно выполнять какие-то действия с добавленной документацией, необходимо обеспечить, чтобы проект выводил документацию в виде XML-файла.

Для этого необходимо изменить настройки компоновки проекта, как показано на рис. 31.5.

с or f.gu ifco ActM* 0 bu9l

P1 f rm A(tl

8u a* DMue

Ceooibonw (omp.iiOon fyr>Do i:

.5 tfTOn ina w m r,fli

[г- 7Т.;т1

output г -

bin\DfOuB\Di g nm t>rt)ot.iim nt tiooJCMl

i-i.......

Puc. 31.5. Установка вывода документации в виде XML-файла