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

Д

Анная глава посвящена написанию и генерации документации для разрабатыва­емого проекта. В первых разделах речь пойдет о задаче комментирования кода с теоретической точки зрения. Последующие, более технические, разделы точно объяснят, как преобразовать введенные комментарии в Javadoc-документацию. Не обманитесь насчет теоретического материала на первых страницах главы: в них со­держится и много сложного технического материала по JBuilder.

Javadoc-комментарии представляют собой последовательность автоматически сгенерированных HTML-файлов, хорошо отражающих структуру программы. Про­сто правильно комментируйте свой код, и Javadoc автоматически преобразует эти комментарии в аккуратно оформленную документацию по продукту.

Написание наилучшей документации предполагает нечто большее, чем просто комментирование кода. Вам потребуется добавить к этому еще несколько файлов. Эти файлы должны содержать обзор всего проекта и всех пакетов, входящих в его со­став. Добавление этих дополнительных файлов не обязательно, тем не менее, я на­стоятельно рекомендую включать их. Как будет показано, вы сможете автоматичес­ки интегрировать их в свой комплект Javadoc-документации.

Кроме того, мы посмотрим, как с помощью JBuilder можно легко и просто напи­сать подробные и хорошо структурированные комментарии. JBuilder не может на­писать комментарии за вас, но зато может помочь правильно отформатировать ваши комментарии, прокомментировав каждый параметр, и несколько упростит за­дачу их написания.

В главе 7 было подробно описано, как с помощью JBuilder просматривать Javadoc-документацию в среде IDE. В данной главе речь пойдет о том, как создавать эту самую Javadoc-документацию.

Комментирование кода

Почему программисты так небрежно относятся к комментированию своего кода? Возможно, потому что большинство программистов сильны в математике, а не в эпистолярном жанре. Лишь очень немногие и хорошо пишут, и хорошо подкованы математически. Может быть, еще одним фактором является то, что лидеры сообще­ства программистов не подчеркивают эту часть своей работы. Например, создатель операционной системы Linux Линус Торвальдс (Linus Torvalds) написал на своей до­машней странице следующее:

"Если вам нужна информация по Linux, поищите ее где-нибудь в другом месте, поскольку я не умею писать документацию."

Андерс Гейльзберг (Anders HejIsberg), создатель Turbo Pascal, обладатель приза "За блестящее программирование" журнала доктора Добба (Dr. Dobb’s Journal) за 2001 год и главный архитектор языка C# компании Microsoft, был знаменит во вре­мя работы в компании Borland тем, что не писал комментарии даже к наиболее сложным участкам своего ассемблерного кода.

И вот мы добрались до основы всех основ: большинство программистов не любят писать документацию. А великие программисты, на которых мы все хотим быть по­хожими, не подают в этом достойного примера.

Но я не Андерс и не Линус, да и большинство программистов, которых я вцдел, не работают на их уровне. Для большинства из нас комментарии являются одним из наиболее полезных и важных средств, доступных нам как программистам.

примечаниеПочти весь JDK великолепно комментирован. Я пользуюсь комментариями в исходных файлах JDK как основным источником информации о программирова­нии на Java. Когда мне нужно комментировать свой код, лично я стараюсь следовать примеру разработчиков из компании Sun.

M*∙Λtt**⅛i∙iMΛβ Дабы не выглядеть совершенно святым, могу заверить вас, что я сам слишком часто не комментирую свой код так, как надобно. От этого больше всего страдаю я сам. Я потратил много часов, разбираясь в текущем состоянии старых проектов, которые в свое время поленился снабдить надлежащими комментариями. Так что вся эта глава отчас­Ти является длинным нравоучением себе, чтобы наставить себя на путь истинный.

Человек против машины

Очень немногие программисты с удовольствием комментируют свой код. Поэто­му я хочу немного поговорить о том, что вы можете сделать, чтобы получить в своем коде приличные комментарии, прилагая минимальные усилия.

Чтобы понять, как оформить свои комментарии, вам придется напрячься и по­нять, чего вы хотите добиться. Это не такой простой вопрос, как может показаться.

Компьютерные языки созданы, чтобы общаться с компьютером, а ваш родной язык — чтобы общаться с людьми. Наше сознание не настолько точно и надежно, как компьютер, однако оно намного гибче и сложнее. Поэтому жестко структуриро­ванные логические конструкции, из которых состоит компьютерный код, является далеко не лучшим средством для обмена идеями с читателем-человеком. Наше со­знание не так ориентировано на детали и не так логично, как процессор, но зато мы можем обобщать и делать выводы на основе здравого смысла, к чему компьютеры еще даже близко не подошли.

Я хочу сказать, что компьютерные и этнические языки выполняют существенно различающиеся задачи. Комментируя свой код, я пытаюсь заполнить промежуток между человеческим образом мышления и компьютерным способом обработки ин­формации.

При написании кода мы записываем алгоритм, шаг за шагом, на очень конкрет­ном языке. При комментировании кода мы делаем обобщения. Например, мы гово­рим: "С помощью этого объекта можно выбрать из базы данных информацию о па-

примечаниеЦиенте". Обычно такая общая информация ничего не значит для компьютера, но человек прекрасно поймет, что вы имеете в виду.

Не обращайте внимания на тех, кто говорит, что обобщения и аналогии — признак эмоционального мышления. Именно в силу нашей возможности обобщать и проводить аналогии мы, люди, являемся такими многосторонними и производительными мыслителями. Компьютеры отстают от нас, потому что они работают только с деталями и никогда не обобщают. А их неспособность к абстрактному мышлению сильно ограничи­вает их применимость.

Компьютеры могут понимать лишь код. Они ничего не поймут в таком сложном языке, как русский. Люди же могут и читать по-русски, и понимать программный код. Но большин­Ство из нас лучше понимает русский текст, чем текст на Java.

Часто цель документации — показать "лес", спрятанный за написанными нами "деревьями" кода. Найдите абстракцию, лежащую в основе деталей, и вы сможете быстро и легко прокомментировать свой код.

Три уровня завершенности комментариев

В последующих разделах я покажу вам три различных уровня документации. Я, по крайней мере, до некоторой степени, призываю к использованию третьей из этих трех технологий. Хотя, как вы увидите, она несколько идеализирована. Я ду­маю, что в реальности хорошо, если большинство программистов достигнут хотя бы второго уровня комментированности кода, о котором я вскоре расскажу.

Код без комментариев

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

■ Особенно тщательно выбирайте имена переменных.

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

■ Каждый незавершенный и запутанный фрагмент кода снабжайте заметками todo. Расскажите тому, кто будет сопровождать ваш код, что вы не доделали.

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

Комментирование каждого объекта и метода

Если вы решили снабдить свой код комментариями, продвигайтесь извне вов­нутрь. Сначала комментируйте пакеты, затем каждый объект, и, наконец, каждый
созданный вами метод. Даже простейшие комментарии на уровне пакетов сослужат вам хорошую службу.

Например, вы можете работать в таком порядке:

1. Создайте обзорный HTML-файл, описывающий каждый пакет вашего проекта.

2. Комментируйте каждый пакет в отдельном HTML-файле.

3. Откройте исходные файлы и прокомментируйте каждый класс из своих пакетов.

4. примечаниеЕсли позволяет время, перейдите к открытым методам и, возможно, некото­рым защищенным методам ваших классов. Если все еще хватает времени, снабдите комментариями объявления данных и даже приватные методы классов.

В составе Javadoc есть хорошо определенная система создания обзор­ной документации проекта и описаний его пакетов, классов и методов. Эта система бу­Дет рассматриваться во второй половине данной главы.

Главное здесь — не забывать о цели: вы не комментируете детали, а даете обзор написанного вами кода. Если есть время, можно перейти и к деталям, но начните с обзора.

Основная задача — помочь человеку, ничего не знающему о вашем проекте, оз­накомиться с его базовой структурой. Для этого напишите краткое, состоящее из двух-трех предложений, описание каждого из пакетов и классов. Если сможете, со­жмите описание до одного предложения. Старайтесь, чтобы словам было тесно, а мыслям просторно. После этого вы можете добавить подробности, но начните с са­мого главного.

Большинству программистов детали нужны только после того, как они поймут структуру вашей программы. Если, например, вы знаете, что структура данных явля­ется бинарным деревом, то тогда вам нет необходимости объяснять, что происходит при добавлении или удалении узла из дерева. Большинство программистов могут сообразить это самостоятельно. Но им необходимо описание самого класса, чтобы не пришлось просматривать каждый метод для вычисления назначения всего кода!

Теперь вы имеете представление о том, как документировать свой проект. По-мо­ему, это все нужно делать большинству людей. Но есть еще одна, высшая стадия, к которой вы можете перейти, если хотите сделать свой код действительно читабель­ным.

Полное комментирование кода

Полностью комментированный код полностью понятен читателю без необходи­мости просмотра хотя бы одной строки кода. Рассмотрим следующий простой ме­тод:

/**

* Этот метод возвращает первое слово из строки

*

* Qparam value Обрабатываемая строка

* Qreturn Первое слово из переданной методу строки

*/

Public static final String getFirstWord(String value)

{

∕∕ Удаление всех пробельных символов String CleanValue = value. trim () ;

∕∕ Поиск индекса первого пробела

Int IndexOfFirstSpace = CleanValue. indexθf(, ‘) ;

// Если строка состоит из одного слова, вернуть ее if (CindexOfFirstSpace ≈ О) ∣∣ CindexOfFirStSpace == -1))

{

Return CleariValue;

)

// Возврат первого слова строки

Return CleanValue. substring СО, IndexOfFirstSpace);

}

Прочтите комментарии к этому методу, не глядя в сам код. Дочитав до конца, вы получите хорошее представление о том, что делает этот метод. Вы можете глубоко понять метод, даже не читая сам код.

Строки кода и строки комментариев присутствуют в соотношении почти один к одному. Вместо того чтобы читать код, вы можете просто прочитать комментарий. Это один из простых способов проверки логики программы и того, что код хорошо документирован.

Не во всех методах нужно комментировать каждую строку. Часто достаточно ком­ментировать блоки кода и оставить на усмотрение читателя детальность прочтения кода. Рассмотрим, например, следующий фрагмент кода:

// Посимвольное копирование строки в обратном порядке for (int i = 1; i < (len + 1) ; i++)

{

Result += stringToReverse. substring(len — i, (len — i) +1) ;

}

Здесь один комментарий поясняет четыре строки кода. И это нормально, по­скольку любой достаточно квалифицированный программист может прочитать комментарий, а затем, просто увидев цикл, понять, что в нем делается.

Технология, основанная на теории

Пора прекратить разговоры о комментировании кода и показать, как с помощью JBuilder и SDK Java создавать великолепную документацию, затрачивая минимум усилий. Сначала в данном разделе мы увидим, как JBuilder облегчает задачу ком­ментирования кода, а в следующем разделе — как с помощью JBuilder создать из этих комментариев Javadoc-документацию.

JBuiIder и комментарии

C помощью JBuilder можно писать хорошо структурированные комментарии, которые затем легко переводить в Javadoc. Javadoc-κoM>..~HτapHH должны начинаться с прямого слэша и двух звездочек /** и заканчиваться одной звездочкой со слэшем */.

Между ними находятся комментарии, дескрипторы, начинающиеся с символа 6, и иногда HTML-дескрипторы, вроде <р>. Обо всем этом будет более подробно расска­зано позже в данной главе. А пока давайте посмотрим, как с помощью JBuilder ре­дакции SE или Enterprise написать код с таким синтаксисом.

Пусть у нас имеется следующее объявление метода: public static final String getFirstWord(String value)

После написания этого объявления поместите курсор перед словом public и введите прямой слэш и две звездочки:

/♦♦public static final String getFirstWord(String value)

B данный момент курсор должен находиться после третьего символа, т. е. после звездочки и перед буквой "р". Нажмите клавишу Enter. JBuilder автоматически вве­дет следующий код.

/**

*

* 6param value

* бreturn */

Public static final String getFirstWord(String value)

JBuilder вставил дополнительные звездочки, символы, закрывающие коммента­рий, и дескрипторы Брагат И βreturn. Вставленный здесь код комментария подго­товлен специально для того, чтобы вы могли создавать хорошие Javadoc-файлы. Те­перь вы можете на свое усмотрение заполнить эти комментарии примерно так:

/**

* Этот метод возвращает первое слово, содержащееся в строке.

*

* браг am value String — из него выбирается первое слово.

*

* бreturn Первое слово, содержащееся в строке, передаваемой в качестве

* параметра. Если в строке только одно слово, возвращается значение

* value. Если строка пуста или null, возвращается пустая строка.

*/

Public static final String getFirstWord(String value)

B последующих разделах данной главы вы узнаете, что утилита Javadoc компании Sun может проанализировать комментарии подобного рода и перевести их в HTML- код, показанный на рис. 21.1.

При вводе кода все редакции JBuilder оказывают помощь в наборе ваших описа­ний. Например, если вы находитесь в середине блока комментариев, JBuilder авто­матически вставляет пробел и звездочку в начало каждой набираемой вами строки. Пусть, например, у нас имеется следующий комментарий:

/**

* Метод, возвращающий первое слово, содержащееся в строке.

*/

Если вы установите курсор после второй строки и нажмете клавишу Enter, JBuilder автоматически введет за вас следующий код:

/**

* Метод, возвращающий первое слово, содержащееся в строке.

* I

*/

Вертикальная черта в третьей строке этого фрагмента кода показывает место, куда JBuilder помещает курсор. Вроде бы мелочь, но она значительно упрощает за­дачу написания комментариев

Дополнительную информацию о создании комментариев вы найдете ниже в дан­ной главе, в разделе "Дескрипторы Javadoc и подсветка синтаксиса".

Использование Javadoc

JBuilder упрощает применение Javadoc — инструмента, входящего в JDK. Javadoc выбирает из вашего кода комментарии и собирает их в отдельных файлах, где их лег­ко можно просмотреть. Кроме того, вы также можете просматривать Javadoc-файлы на панели Doc среди закладок просмотра файла. Например, если вы просматриваете JFrame, JAppiet Или любой другой исходный файл JDK, и перейдете в панель Doc, вы увидите Javadoc-документацию для того или иного файла.

Javadoc также позволяет документировать пакеты и создавать обзорный файл для всего проекта.

Если вы правильно прокомментируете свой код и добавите описания пакетов и обзорный файл, Javadoc сможет эффективно и оперативно документировать цели­ком весь проект. Поскольку Javadoc работает с объявлениями и комментариями, эта утилита может быть запущена на ранних стадиях работы над проектом, содержащим заглушки. По мере добавления новых методов и комментариев вы можете пересоз­давать Javadoc, таким образом постоянно автоматически обновляя документацию проекта.

рис. 21.1. простые комментарии, переведенные утилитой javadoc

Доклеты

Класс, содержащий инструкции по содержанию и форматированию выходных Javadoc-файлов, называется Доклет (doclet — "документик"). В Мастере создания Javadoc-документации JBuilder предлагает вам выбрать: использовать ли стандарт­ный доклет (по умолчанию), или более старый доклет JDK 1.1. Каждый из этих классов генерирует из ваших комментариев HTML-файлы, но более новый стандарт предлагает большую степень детализации.

Javadoc можно запустить для пакета или отдельных исходных файлов (с расшире­нием . java). Но все же JBuilder характеризуется отчетливым уклоном в сторону до­кументирования пакетов.

примечаниеJavadoc является частью семейства разработанных Sun утилит командной строки, таких как Jar, Javac И Java. В JBuilder редакций SE и Enterprise входят мастера, су­щественно упрощающие использование Javadoc.

Если вы работаете в JBuiIder редакции Personal, то, возможно, вам будут интересны следующие средства:

■ Javadoc Wizard Free. Этот инструмент разработан Гилмером Дерджем (Gillmer Derge), почтовый адрес SpamGgillmerderge. сот. Инструмент доступен для бес­платной выгрузки на сайте Http://codecentral. borland. com под номером 15540. Полный URL-адрес выглядит так: Http://codecentral. borland. com/ codecentral∕ccweb. exe/listing? id=15540.

■ Javadoctool Personal OpenTooI. Разработан Валентино Кирьякидесом (Valentino Kyriakides), которому можно написать на vkyrGlavielle. com. Этот условно- бесплатный продукт немного похож на мастер Javadoc. Продукт доятупен для выг­рузки на сайте Http://codecentral. borland. com под номером 17606. Полный URL-адрес выглядит следующим образом: Http://codecentral. borland. com/ codecentral/ccweb. exe/listing? id=17606.

Сначала вы ознакомитесь с тем, как создавать Javadoc-документацию с помощью средств JBuilder. После этого вы узнаете, как работать с Javadoc в командной строке. В дальнейших разделах будет показано, как самостоятельно вставлять дескрипторы.

Если вы хотите углубиться в эту тему чуть больше, нежели изложено в данной книге, то компания Sun разместила на своем Web-сайте обширную документацию по средству Javadoc. На момент публикации эту полную документацию можно было найти на сайте Java. sun. com, Воспользовавшись поисковым средством для нахож­дения слова Javadoc.

Мастер создания Javadoc

В данном разделе описывается методика подготовки документации с помощью средств JBuilder. Начните с создания приложения, как было описано в главе 3.

После создания приложения панель проекта JBuilder будет содержать три файла:

■ Файл проекта, с расширением. jpr или. jp×.

Applicationl. java.

Fra mel. j ava.

примечаниеЕсли вы выберете создание файла примечаний к проекту, то в панели проекта будут присутствовать четыре файла.

C помощью мастера создания Javadoc добавьте в это окно новый узел. Перейдите к закладкам просмотра файла внизу панели содержимого и щелкните на закладке Doc. Пока что вы видите почти пустой файл.

В главном меню выберите пункт Wizards ∣ Javadoc. Появится окно мастера созда­ния Javadoc-документации. На первом шаге мастера выберите Standard Doclet (Стан­дартный доклет), как показано на рис. 21.2.

Щелкните на кнопке Next, чтобы перейти к шагу 2 мастера (см. рис. 21.3). Здесь вы можете изменить имя доклета и выбрать каталог, в котором необходимо сохра­нить результат. Пока оставьте все эти настройки такими, как предложено по умолча­нию. Убедитесь, что опция Show console output (Показывать консоль протокола) включена, a Always run Javadoc when building the project (Всегда запускать Javadoc при сборке проекта) — выключена. Просмотр консоли протокола позволит вам видеть все предупреждения Но автоматический запуск Javadoc при каждой сборке проекта увеличит время его компиляции и, скорее всего, является лишним для большинства разработчиков. При смене JDK на более новую версию часто улучшается и работа средства создания Javadoc, поэтому, если вы запускаете приложение в более новой версии JDK, чем используется в JBuilder, отметьте флажок Use project JDK when running Javadoc (При запуске Javadoc использовать JDK проекта)

На третьем шаге мастера вы можете задать конкретные пакеты проекта, которые необходимо документировать (см. рис. 21.4). По умолчанию документируется весь проект. Если вы уберете отметку с флажка документирования всего проекта, появит­ся список пакетов, содержащихся в проекте, и вы сможете добавлять и удалять паке­ты из этого списка.

Переключатели внизу окна шага 3 позволяют задать степень полноты создавае­мой документации. Выберите Public, если вы хотите видеть только открытые классы и их члены. Выберите Protected для документирования и защищенных, и открытых классов и членов. Выбор кнопки Private создаст документацию по всем классам и членам вашего проекта

рис. 21.2. шаг 1 мастера создания javadoc- документацииjavadtm. wizard slep 1 of 4poetetnamdjstandard dociet peaenptton
,tws doeɪet is provided by itie jok and produces t jt4'
Okmsu л аосж

Doetets are usetfto customize tħt content and format AtJavadoc output

^3

s ⅛

I ≈-

∙⅛ill⅛l⅛⅛⅞⅛⅜⅝f-
Γ⅛te
caneat

t

На рис. 21.4 видна еше одна опция, связанная с видимостью. Если вы выберите вариант Package, в каждом пакете, в добавление к открытым и защищенным клас­сам вашего проекта, будет просмотрен и переведен в Javadoc специальный файл. Цель опции Package состоит в том, чтобы дать возможность документировать паке­ты проекта. Я считаю эту возможность очень важной и расскажу о ней позже в дан­ной главе, в разделе "Комментарии уровня пакета".

А пока что выберите опцию Private. В результате вы получите наиболее полный обзор созданного вами приложения.

После щелчка на кнопке Next и перехода к шагу 4 процесс выбора содержимого вашей документации продолжается, как показано на рис. 21.5. В нашем примере отметьте в мастере все стандартные опции и дескрипторы, кроме Separate index per letter (Отдельный указатель для каждой буквы).

Имеется еще и текстовое поле, в котором можно задавать дополнительные оп­ции. Примеры применения этого поля можно найти далее в этой главе, в разделах "Обзорные комментарии" и "Опции Javadoc".

о javadoc wizard - step 3 of 4,β⅛⅛4je⅛ • лешг,« psfe⅛,e project,t≈∙ pmete
рис. 21.3. шаг 2мастера создания javadoc-документации
s*toαn∙lnju> jnawmi b<χtnv' 4
seiwrtwnitnpecitageeinirourprojeatooocwtiem anopacκajenwnee orevntvredthen епциате ibeebi thede⅛uttpaεbea∙ wbtbettocumented. ⅛me ithi 4∣ oftteee1 rode'1’ijember msuroeinim йо wn√mwn
,uiwestirtetbibbitodocwnent p κwt г pngected,< f⅛tjw∏.
рис. 21.4. шаг 3 мастера создания javadoc- документации

Щелкните на кнопке Finish. Сразу после выхода из мастера создания Javadoc-до — кументации вы увидите в панели проекта новый узел с названием Standard Dociet (Стандартный доклет).

Решения, принятые при работе с мастером создания Javadoc-документации, можно изменить в любое время. Щелкните правой кнопкой мыши на кнопке Standard Doclet и выберите пункт Properties — и вы опять попадете на только что рассмотренные страницы.

Генерация документации

C помощью проводника Windows, KDE Konqueror или любого другого диспетче­ра файлов просмотрите содержимое каталога, содержащего ваш проект. Вы увидите каталоги Classes И Src. Если вы еще не запускали мастер создания Javadoc-доку­ментации, то каталог Doc Не должен существовать. (Для целей обсуждения удалите этот каталог, если он вдруг существует. Все его содержимое будет заново сгенериро­вано мастером создания Javadoc-документации.)

Рис. 21.6. Панель Doc Перед запуском доклета

Рис. 21.5. Шаг 4Мастера создания Javadoc— документации

{3} JBurfder C√Doeunτents and Settings.* AdmHMsfr л *

F«a Edtt Saatcr view Projeei Rur Tearr Wzarot Теме vvtreow j⅛βιp □ ⅛ M Ad2

⅛1 I/ ’ ⅜,4⅜ , ⅞T<

U <3jJ "ɔ- ⅛ Framel];

.. — … ⅛Sjef¾gj

*sp untltled33 ∣px j i¾ Ohi untitled33 1 -∙ c⅞* Standard Doclet I ; ⅛⅛ Applicatlonljava 1 4k Frame1 .Java

∣⅛^cVuntihed33tdoc⅛nhtled3⅛ramθ1.html

Urrtitl∙d33 Class Framel

Public class Framel

Extends JFrame

Title:

Description:

Copyright: Copyright (c) 2002 Company:

Ггадаюаеочмсятаtxx гммачиа arβ⅛WAdπιwe⅛

θ,jrce Des¾n)⅞wh⅛∙ B⅛t -]History]

Вернитесь в JBuilder и щелкните на закладке просмотра файла Doc браузера при­ложения. Теперь вернитесь в диспетчер файлов, и вы увидите, что в каталоге вашего проекта появился подкаталог doc.

ПРИМЕЧАНИЕ

Если вы удалили из каталога проекта подкаталог doc, а затем выбрали закладку Doc, есть вероятность получить сообщение о какой-то проблеме. Если это слу­чилось, выберите другую закладку просмотра файла, а затем вернитесь опять к закладке Doc. После этого все должно быть нормально. Каталог doc создастся после повторного Выбора закладки Doc.

В этом новом каталоге будет находиться HTML-файл. Этот же файл появится в панели содержимого JBuilder при выборе закладки Doc, как показано на рис. 21.6. Упомянутый файл создается JBuilder и не входит в состав стандартного доклета.

Теперь убедитесь, что в панели содержимого выбрана закладка просмотра файла Doc, и посмотрите, что будет дальше.

Щелкните правой кнопкой мыши на строке Standard Doclet и в появившемся всплывающем меню выберите пункт Маке. Комментарии и код из ваших исходных файлов будут автоматически преобразованы в HTML-документацию и помещены в каталог Doc. Откройте в панели проекта узел doclet и выберите строку index html. Вы увидите, что в панели содержимого появилась официальная Javadoc-документация для вашего проекта (см. рис. 21.7).

Если теперь вы заглянете в каталог Doc, То увидите довольно много новых фай­лов, как показано на рис. 21.8. Вы можете открыть их непосредственно в диспетчере файлов — они будут просматриваться как любые другие файлы с таким же расшире­нием. Например, вы можете просмотреть HTML-файлы в своем Web-браузере. Для этого просто дважды щелкните на строчке index. html в диспетчере файлов.

Jx∣∏∣2y

Rile Edit Searth View Prolect Run team Wizaras Tooie Winoaw Heip , ʌ

M lAr. a awt 3⅞4 ⅛

As a ®.>

Jp untitled33.jpx æ Φ «Project Source* æ ft untrtled33 1 Й [∣*StandbrdDoaet

X∣⅛Frame1

Ig «■ — S ∣∣∣ntsand Settings∕margie∕jbprojecVuntitled33∕doc∕indθxhtml

IiffiMHCiass Tree Deprecated Index Help

Ыюмсмюе nextmcwce Ee⅝mei no eejhe>

AU

Classes

App⅛c⅝⅛ont

Frsmet

Рис. 21.7. Панель Doc После запуска доклета и выбора строки Index. html В узле Doclet Панели проекта

⅛⅛ Applicationl. java ^ Framet java ⅞3 untitled33.html

Class Summary

* ɪ..

!Applicationl

Title:

!Framel

Title: ……..

Package untitled33

IgrffffiHciass Tree Deprecated Index Help -⅜1-⅛.∙C — a⅜>J MEVESCWOE HextmcWoe…………………………………………. ГЕАМД MflfRAlia_____ J⅛f;

WiAXruments and Serings⅛wrθMbpr4βctAr⅛ed33⅛(JhΛxl*n∣

ПРИМЕЧАНИЕ

Дополнительная информация о просмотре Javadoc-файлов приведена в Разделе "Просмотр Javadoc-файлов с помощью браузера" в конце данной главы.

Javadoc-файлы

Просмотрите файл Index. html, Который является страницей Package (Пакет) или обзорной страницей. Вы можете увидеть ее в панели doc, как показано на рис. 21.9. Отсюда можно переходить по ссылкам на классы вашего пакета, в данном слу­чае — на Applicationl И Framel.

Ft C:\Documents and Settings’ Administrator’ Jt,μ∏> t1 ‘⅛⅛rf-

^favorites Tools HeJp

⅜j J ,⅛arch ⅛j Folders JJ X

Address jθj C:\Dogjments and 5ettings∖⅜drninistrator⅛pro)eccljrtιCedJS-, ∣

: Foders

~.X⅛⅛X) — X X⅛⅞

Рис. 21.8. Каталог Doc, Содержащий новые файлы документации

Рис. 21.9.

Обзорная страница или страница Package

ʌ; .∙⅛⅛: 3ι∣^⅛fe⅛⅛⅛P^J

S O src
B ɛ] untιtled33

It. Ql classes ; L⅛ td doc

Й Qj src ffl Qj untitled34 Й-Q untitted4 ffl O untitted5 B-Q untitled6 ⅛Q unttled/ ffl Cj untitled8

Natna

A

Quntitled33

Alldasses-frame. h…

Il

@ deprecated-list. html

41

4 ‘ Hdp-doc. html

81

⅛j index. html

Il

⅛) index-al. html

71

Overview-tree. html

51

Rlpackaqe-Ist

11

&J packages. html

Il

<Q serialized-form. html

51

Ristylesheetxss

21

J,,… ,ɪ,

±j

11 object® (Oiskfree space∕314 MS) 29.7 KS ⅛ My Computer

0 JBtiilder 7 — C: Dotuments and 5etHngs∕matgie∕∣bpτo)ett∕un>ft. led^3∕κ — t a *>4 sb «

File Edit Search Vie* Proiect Run Team Vfizaros Tools Vflndnw Heta

⅛J. ⅞ * ∙oi,

⅛-i⅛∙r∙

4⅜ ljava. awt

WJJ3l×l

~3 ft

Fφ untitled33jpx J ∙⅛ A «Project Source* I æ flk untitled33

Я æ t? Standard Doclet i Applicationl Java

Untitled33.html

; . ∙∙’∙∙ ⅛ .÷a> X⅛ . :i <:: »■ ‰S⅛ ^X¾⅛⅛ .⅞’⅛>⅛√⅞ ⅛⅛⅞’ Ж 3÷< ;>«& if ⅛^⅞3Sb⅛S⅛-X ⅛: λ- v’«

X A FrameI [ χ ⅛⅛ index]

∙<a ⅜a ⅛ Ifj ∣∕jbprojecVuntitled33∕doc∕u∩titled33ipackaQe-summar∕l^tml

Iill.! ½M J Class Trap Deprecated INdex HelP

FEEV FFCKAGE HEXTFACkAGE FE⅛ME1

Package untitled33

Class Summarv

I Applicationl Title:

IFramet j Title:

_________________________

1

L¾T⅛⅞TtH Class Tree Deprecated lndnx Help

√l∖evf*w** "e22E! SiF_______ __________ .дццд_^г)?.Ам„ы.

RfeJ⅛β∣ JOC (jojMrnκrfs⅛nα j«dinjj! *™rgx-Jb)a jpςiHjr*> — d33llπoc-vxi)"d334>4PW∣g< SOjroe Pe⅛∣gπ j Sean ∣ JMI p∣ c History (

примечаниеНажав комбинацию клавиш Ctrl+Alt+Z, можно увеличить область про­Смотра, закрыв панели сообщений, проекта и структуры.

Со страницы Package можно выйти на другие страницы документации. Щелк­ните на слове Applicationl, и вы перейдете на страницу Class, которая показана на рис. 21.10. Здесь видно, что класс Appiicationl Является производным от Java. lang. object. Эта страница содержит описание класса и описывает все его поля, методы и конструкторы. Присутствует также и список всех унаследованных методов. Обратите внимание, что когда вы находитесь на странице Class, ссылки на другие страницы документации все равно активны.

.iotxl
fife sdtt search view prolect run teeto vflzarde loots vflndow heto
b's≤-⅛ι a, ½ * ¾ Λss aΚ∣ -w-
* -* ∣e .
u .bia∣5∙ ⅛ρ**ι∣
⅛ untιtled33.jpx 1 æ tf> untitlβd33 ⅛ standard doclet i : ∣⅛ applicationl java i i& frame1 java
,q lbudder о docunients and setttfxjs/adσitftf⅛traf •,(jj ⅛* ⅛ й f jatorflbprojectjuntιt∣ed33jdocjunlltled33japp∣icationt .html
package bbbiliee tree deprecated index help
,mievciaes hmtr-j»5i
summary, mmhi piclc ∣caa⅞τιι) ι∣grnao
,пиан, ио див omam- hild ∣ cailcth ∣ bfrkciit
рис. 21.10. страница class

Теперь перейдите на страницу Tree (Дерево), на которой отображена иерархия классов вашего пакета (см. рис. 21.11).

Untltled33

Class Applicafionl

Java. lang. Objecc I

M—untltled33 .Application!

……………………. -……………………. —………….. — d

VftJSWil nJlieAtcxjaRnrtsBiwseeingsjAdrt-JretixdbprcieclAjrtitIexOaHc Jurt S⅛dtτ⅛fp⅛M jnlSea⅜ιl¾⅜lfθocj⅞⅛⅛∣Γ »’ rr’r ^"" ‘"l" ^τ’p^’ "" ,l

ponterrtpanvtetoroerlayoud

<^P⅜⅜

Ple BcBt gearct. 1.λw Protect Ruo Ifesm R⅛o⅛ ¾⅛π¾⅛ Tft⅛

ND⅛f.⅛∣∣⅛⅛ ‘ fc ∙

J ✓ ∙ ⅛ ’ ¼ ∙ i a — *∙ ∙* i

■ X ⅛ FrMmet ∣ ⅛¾ ⅜M⅛4- _______ __

»4 4»" « Itf ∣∕fflleJ∕JC.(Documentsand Settlngs∕margleflbproiectJuntltled33Jdoc∕urttitled33∕package-treeħtml Package Class BWiDeprBcatBd Index Halo

FRCV HBCT ZSAHCl №SUKa

рис. 21.11.
иерархия классов
Hierarchy For Package υntitled33

Class Hierarchy

* class java. lang. Object

• class untitled33 ABDlicatInnt

* class Java awt-Coinponent (IrnpleiTtentsjava awt image ImageObseiver, java. Swt MenuContaineii java io. Serializable)

* classjava. awt. Container

* class java. awt Window (implements javaκ.accessibility. Accessible)

* class java awt. Frame (implements java. awt. MenuContaineι)

* class javax swing JFrame (implements javax. accessibility. Accessible, javax swing RootPaneConIainer. javax Swing-WindowConstants)

• class untιtled33.ξpuusl _ _ -5⅛

⅞⅛ c⅜∣J>es⅝ ,j Bear I VXljt

HX US dedWP>β — И HiVtpIUd BtAdteJr 41

Если вы щелкнете на слове Index в навигационной панели, то сможете получить информацию обо всех частях компонентов пакета, как показано на рис. 21.12. На­пример, найдите на странице Index строку Applicationl; она представлена как класс. Если щелкнуть на ней, JBuilder перейдет на страницу Class для Framei.

Кроме уже просмотренных страниц, существуют и другие. Страница Use (Ис­пользование) содержит список элементов кода, использующих любую часть рас­сматриваемого пакета, класса или интерфейса. Страница Deprecated (Нерекоменду­емые) покажет все использования нерекомендуемого кода. Учтите, что эти страни­цы генерируются не всегда. Они появляются, только если на шаге 4 мастера создания Javadoc-документации вы отметили, что хотите документировать дескрип­торы @use И Odeprecated. Страница Help (Справка) кратко описывает все страни­цы, и ее стоит внимательно прочитать.

Часто бывает удобно просматривать документацию, сгенерированную Javadoc, не в панели содержимого, а в браузере, открытом для файла Index. html, Расположен­ного в каталоге Doc. При повторной генерации страниц лучше использовать этот подход, поскольку у JBuilder могут возникнуть проблемы со сменой отображения. Подсказки на эту тему находятся в разделе "Просмотр Javadoc-файлов с помощью браузера" в конце данной главы.

Комментарии уровня пакета

Ранее я упоминал о возможности сгенерировать Javadoc-документацию, содер­жащую комментарии о вашем пакете. Эти комментарии появляются в Javadoc-фай- лах, если в мастере создания Javadoc-документации была выбрана опция Package или Private, как показано на рис. 21.4.

j) hhiilrier 7 - c:, docuniaits rf∏d sfttiπys∕⅛n∂ry∣e∕⅛)ptθΛw ' г/.?*,'.',.* * *÷s *,xas framei j × ⅛ index∣ j ⅛
⅛∙ "* зэ ■ jrffemiemjdocijmente and settlngslmargleflbprojecuuntit
,package class tree deprecated ibffjhi help

File Edit Search yw« ProjecI Run Team M Jjarc5rf 1

PRCV NEXT

рис. 21.12.
страница index
ABCFMEU

AppIiQatiftnl — class untitled33.⅛jp⅛5li2βl.∙

Title

AnoHcationtft— Constructor tor class untitled33.j

HmderLavt)ut1 — Variable in class untitled33.Frgniel

‘rtτflrtilβjβt.Λ rυβ>βtsβndS SourceJ Design Bean j UMLj Doc JHtetotyj

Build succeeded Wltn onias complied. Bufifl tooκ4 seconos

Применяемая техника очень проста. В каждый создаваемый пакет необходимо добавить файл с именем package. html. Исходный код этого файла может быть ос­нован на официальном шаблоне Sun для файлов пакетов, который приведен в лис­тинге 21.1.

Листинг 21.1. Официальный шаблон от компании Sun Для генерации Javadoc-комментариев для каждого создаваемого пакета. Удалите разделы, помещенные между символами

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final∕∕EN">

<ħtml>

<ħead>

<∙-

θ(#)Package. html 1.60 98/01/27

Copyright 1998 Sun Microsystems, Inc. 901 San Antonio Road,

Palo Alto, California, 94303, U. S.A. All Rights Reserved.

This software is the confidential and proprietary information of Sun Microsystems, Inc. ("Confidential Information"). You shall not disclose such Confidential Information and shall use it only in accordance with the terms of the license agreement you entered into with Sun.

CopyrightVersion 1.2

—>

<∕head>

<body bgcolor="white">

##### ЭТО ШАБЛОН ДЛЯ КОММЕНТАРИЕВ PACKAGE DOC. #####

##### ВВЕДИТЕ ЗДЕСЬ ВАШИ КОММЕНТАРИИ К ПАКЕТУ. НАЧНИТЕ C #####

##### ОДНОГО ПРЕДЛОЖЕНИЯ-РЕЗЮМЕ, НАЧИНАЮЩЕГОСЯ C ГЛАГОЛА, ВРОДЕ: ##### Предназначено для…

<Ь2>Спецификация πaκeτa<∕h2>

##### ЗАПОЛНИТЕ ВСЕ СПЕЦИФИКАЦИИ, НЕОБХОДИМЫЕ JAVA COMPATIBILITY KIT «#### <ul>

<liXa href="">##### ССЫПКИ НА ВСЕ СПЕЦИФИКАЦИИ СОЗДАНИЯ ФРЕЙМОВ #####</а> <∕ul>

<Ь2>Другая документация</Ь2>

Обзоры, учебники, примеры, пособия и опсиания инструментов можно найти здесь: <ul>

<li×a href="">##### ССЫЛКИ НА ДРУГУЮ ДОКУМЕНТАЦИЮ #####</а>

<∕ul>

<!— Ниже можно поместить дескрипторы @see И @Since. >

<∕body>

<∕html>

Исходный код между HTM L-дескрипторами <body> Файлов Package. html Будет вставлен в страницы Package ваших исходных Javadoc-файлов. Предоставляя эту ин­формацию, вы обеспечиваете достаточно подробную документацию для проекта в целом.

В исходных кодах, входящих в состав сопровождающих книгу материалов, вы найдете примеры подобного рода файлов для более сложных проектов. Например, файлы пакета содержат программы GridWorld и Breakout.

Обратите внимание, что файл Package. html Должен находиться в том же катало­ге, что и исходные java-файлы. И Более того, этот файл будет включен в Javadoc-до- кументы только в том случае, если в мастере создания Javadoc-документации вы вы­берете опцию Package, как показано на рис. 21.4.

Если вы работаете в режиме командной строки, то в конец списка аргументов утилиты Javadoc добавьте аргумент -package. Техника работы в командной строке объясняется в разделе "Работа с Javadoc из командной строки".

Обзорные комментарии

К этому времени вы имели возможность прокомментировать большую часть ас­пектов своего проекта. Но осталось еще одно: обзор всей программы. К сожалению, JBuilder не очень хорошо поддерживает эту возможность, но, если вы смиритесь с небольшими неудобствами, то сможете получить вполне неплохой результат.

Javadoc автоматически генерирует обзорную страницу для каждого создаваемого проекта, что можно видеть на рис. 21.9. Этот файл называется Index. html, И он яв­ляется первой страницей всех Javadoc-проектов.

К счастью, Javadoc предоставляет средства для вставки текста в обзорную страни­цу. По соглашению, вы должны создать файл Overview. html И поместить его в кор­невой каталог своего проекта. При запуске Javadoc из командной строки восполь­зуйтесь параметром -overview, Который указывает на этот файл. Тогда Javadoc про­смотрит ваш обзорный файл и поместит его первое предложение в свой обзорный файл. Затем весь ваш документ, в том числе и первое предложение, будет добавлен в конец обзорного файла.

На последней странице мастера создания Javadoc-документации имеется поле, с помощью которого вы можете передать Javadoc любые команды. Это поле называет­ся Additional Options (Дополнительные опции), и его можно увидеть на рис. 21.5. Тео­ретически можно было бы в этом поле передать следующий текст:

-overview overview. html

Но это не сработает, поскольку система не сможет найти файл Overview. html, Если вы не зададите путь к нему более подробно.

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

В конце концов, я прекратил поиски решения этого вопроса и просто закодиро­вал всю информацию:

-overview G:/SrcJava/jbbook∕Games∕Breakout∕Breakout. html

Понятно, что вы должны изменить этот код на имя и каталог того проекта, с ко­торым работаете вы.

Для редактирования стандартного доклета перейдите к узлу Standard Doclet в па­нели проекта, щелкните на нем правой кнопкой мыши и в появившемся всплываю­щем меню выберите пункт Properties.

примечаниеПри создании нового проекта с помощью JBuiIder Он генерирует в кор­невом каталоге вашего проекта HTML-файл. Обычно этот файл имеет то же имя, что и проект. Если вы правильно отредактируете его, он сможет послужить в качестве файла, который Javadoc Вставляет в обзорный файл вашего проекта. Преимущество данного метода состоит в том, что такой файл могут легко отыскать другие разработчики, кото­Рые открывают ваш проект, а также те, кто ссылаются на вашу Javadoc-документацию.

Здесь следовало бы сказать еще кое-что. Некоторые проекты, входящие в состав сопровождающих книгу материалов, имеют обзорные файлы, которые удобнее чи­тать как часть документации, созданной Javadoc. На случай, если вы захотите изме­нить их, там обычно присутствует пакетный файл или файл Build.Xml утилиты Jakarta Ant, которые могут быть выполнены в режиме командной строки. C помо­щью этих средств вы можете автоматически повторно сгенерировать Javadoc-доку — ментацию для моих проектов, не обращая внимания на используемые пути исход­ных проектов. Другими словами, запуская утилиту Javadoc из командной строки, вы сможете использовать относительные пути к этому файлу, даже если JBuilder и не позволяет делать это.

Javadoc-дескрипторы и подсветка синтаксиса

Если вы используете ключевое слово языка Java или идентификатор, его следует заключить в дескрипторы <codex∕code>, чтобы в HTML-файле появилась "под­светка синтаксиса". Элементы, которых это касается, включают:

■ Ключевые слова Java.

■ Имена пакетов.

■ Имена классов.

■ Имена методов.

■ Имена интерфейсов.

■ Имена полей.

■ Имена аргументов

■ Примеры кода.

Полный набор правил и предложений по поводу написания Javadoc-коммента- риев выходит за пределы данной книги. Тем не менее, на сайте Sun имеется доста­точно обширная документация на эту тему.

После того как вы сформулируете свое описание, часто возникает необходимость вставлять в него один или несколько дескрипторов. Существуют два вида дескрип­торов. Эти дескрипторы начинаются с символа S и транслируются в некоторую фор­му привлекательного HTML-текста внутри Javadoc-файлов.

Отдельный дескриптор, наподобие Sparam, Должен помещаться после звездочки и пробела в начале строки комментария. В других местах текста утилита Javadoc не распознает его. Отдельными являются дескрипторы Sauthor, Qdeprecated, Sexception, Slink, Sparam, Sreturn, Ssee, Sserial, SserialData, SserialField, Ssince, Sthrows И Sversion.

Внутренний дескриптор заключается в фигурные скобки. Фигурные скобки гово­рят Javadoc, что это внутренний дескриптор, и могут быть помещены в любое место комментария. Внутренние дескрипторы — это (SdocRoot), (SinheritDoc), (Slink), {6linkplain} И {@Value}. Некоторые из внутренних дескрипторов, в том числе {6inheritDoc}, (Slinkplain) И (Svalue), ПОЯВИЛИСЬ ЛИШЬ В Java 1.4.

Чтобы получить актуальный на текущий момент список дескрипторов и описа­ние их применения, найдите на сайте Java. sun. com Документацию по Javadoc (ищите по слову Javadoc). В настоящий момент информация по версии Java 1.4 находится ПО Адресу Http: //java. sun. Сот/ J2se∕1.4∕docs∕tooldocs∕win32∕ javadoc. html#javadoctags.

Опции Javadoc

Дополнительную информацию о поле Additional Options (Дополнительные опции) можно получить из индекса оперативной справки JBuilder, воспользовавшись стро­кой поиска "javadoc documentation viewing, for entire project" и далее "command line options". Просматривая список, вы можете увидеть опции, не предусмотренные в мастере. Другой способ получить список опций командной строки — набрать после символов приглашения на ввод команды Javadoc -help. Третий способ полу­чить опции командной строки предполагает посещение сайта Java. sun. com. Сейчас эта информация находится по адресу Http://java. sun.Сот/J2se∕l.3∕ docs∕tooldocs∕Win32∕j avadoc. html# J avadocoptions.

Ниже приведен список опций командной строки, которые, согласно оператив­ной справке JBuilder, не предусмотрены в мастере. Их объяснения являются усечен­ными версиями информации, доступной на сайте Java. sun. com, И взяты непосред­ственно из документации компании Sun. За дополнительной информацией по по-

Воду использования опций командной строки обращайтесь к документации, доступной на сайте Java. sun. com.

-overview Путь\имя_файла

Задает, что Javadoc должна выбрать текст обзорной доку­ментации из "исходного" файла, заданного как путь \имя_файла, И поместить его в обзорную страницу (overview-summary. html). Путь\имя_файла Задаются относительно -sourСераTh.

-help

Отображает оперативную подсказку, содержащую данный список опций командной строки Javadoc и доклетов.

-Дфлаг

Передает Флаг Непосредственно в JDK времени выполне­ния, под управлением которого выполняется Javadoc. (Например, так можно распределять память.)

-locale

Вариант_языка

Задает локализацию, используемую Javadoc при генериро­вании документации. Возможные варианты: en_us (амери­канский английский) или en_us_wiN (вариант Windows).

-doctitle Заголовок

Задает заголовок, помещаемый в начале обзорного файла.

-Windowtitle заголовок Задает заголовок, помещаемый в HTML-дескриптор <titie>.

-header шапка-footer концовка-bottom текст-link циь_внешнего_ документа-iinkoffline
ииьвнешндокумента
локальннй_список_
пакетов
-group
ваголовок—группы шаблон_пакета: шаблон_пакета:... -nosince
-nohelp
-helpfile
путь\имя_файла
-styleeheetfile путь\имя_файла
-serialwarn
-charset имя
-doencoding имя
Задает текст шапки, помещаемый в начале каждого вывод­ного файла. Шапка помещается справа от верхней строки навигации.

Задает текст концовки, помещаемый в конце каждого выходного файла. Концовка помещается справа от нижней строки навигации.

Задает текст, помещаемый в конце каждого выводного файла. Текст помещается внизу страницы, под нижней строкой навигации.

Создает ссылку на уже существующую документацию, созданную Javadoc, о внешних классах, на которые есть ссылки. Аргумент Икъ_внешнего_документа Является URL-адресом внешней документации, на которую вы хотите установить ссылку.

Пользуйтесь этой опцией вместо — link, если на момент запуска Javadoc файл списка пакетов внешнего документа еще не находится по адресу Икь_внешнего_документа (т. е. находится в "оффлайне"), но существует в другом месте Локальный_список_пакетов (обычно на локальной машине).

Разделяет пакеты обзорной страницы на любые заданные вами группы, по одной группе на таблицу.

Исключает в сгенерированной документации разделы Since, связанные с дескрипторами 6βince.

Исключает ссылку Help в строках навигации вверху и внизу каждой выходной страницы.

Задает путь Путь\имя_файла К альтернативному справочно­му файлу, на который указывают ссылки Help верхней и нижней строк навигации. Без данной опции Javadoc автоматически создает справочный файл Help-doc. html, Встроенный в Javadoc.

Задает путь к альтернативному файлу таблицы стилей. Без данной опции Javadoc автоматически создает файл табли­цы стилей Stylesheet. css, Встроенный в Javadoc.

Генерирует предупреждения времени компиляции об отсутствующих дескрипторах @Serial. По умолчанию Javadoc 1.2.2 (и более поздние версии) не генерируют предупреждения подобного рода.

Задает набор символов для данного HTML-документа. Задает кодировку для генерируемых HTML-файлов.

Если вам хочется в поле Additional Options установить опцию, не приведенную в этом списке, помните, что эта опция перекроет все другие варианты, выбранные вами для этой опции в мастере.

Просмотр Javadoc-файлов с помощью браузера

Не всегда Javadoc-документацию удобно просматривать с помощью JBuilder. Если вам нужна справка об одном конкретном классе, то лучше просмотреть ее в JBuilder. Но он мне кажется не особенно удобным, если требуется просмотреть не­сколько Javadoc-файлов.

Одним из решений может быть добавление Internet Explorer или какого-либо другого браузера в меню Tools JBuiIder. Тогда вы сможете запускать браузер со свои­ми исходными файлами, не покидая JBuilder.

Выберите в JBuilder пункт меню Tools ∣ Configure Tools (Инструменты | Конфигури­рование инструментов) и вы увидите диалоговое окно Configure Tools. После щелчка на кнопке Add появится диалог Add Tool (Добавить инструмент).

В диалоге Add Tool введите в поле Title название браузера. В поле Program с помо­щью кнопки эллипсиса вставьте имя главного файла браузера. В случае Internet Explorer это обычно C:\Program FiIesMnternet ExpIorerMEXPLORE-EXE. В поле Parameters добавьте макрос (SFiIePath). Щелкните на кнопке OK, чтобы закрыть диа­логовое окно Add Tools, и на кнопке Close, чтобы закрыть диалог Configure Tools. В панели проекта найдите строку Standard Doclet (Стандартный доклет) и разверните ее узлы. Выберите с помощью мыши в панели содержимого в Standard Doclet файл lndex. html. Теперь вы можете выбрать в меню Tools название браузера, и в нем ото­бразится исходный текст Javadoc-документа

Раз уж мы говорим на эту тему, то стоит упомянуть, что JBuilder хранит свои справочные файлы и справочные файлы JDK в JAR-файлах инсталляции JBuilder. Найдите каталог JBuilder/doc, А в нем — какой-нибудь JAR-файл. Например, вполне сгодится Jdki3docs. jar Или Jdkl4docs. jar. C помощью стандартной про­граммы вроде утилиты Jar Или WinZip распакуйте все содержащиеся в нем файлы. После этого вы можете просматривать их в проводнике Windows или KDE Konqueror. Иногда так бывает удобнее, чем обращаться к справочным файлам через меню, поскольку в этом случае файл полностью не зависит от того, что вы делаете в рамках графического интерфейса JBuilder.

Должно быть понятно, что вы можете комбинировать обе упомянутые в данном разделе технологии для автоматического доступа к справочным файлам JDK через Internet Explorer или KDE Konqueror с помощью лишь одного щелчка мышью на со­ответствующем пункте меню Tools. Вместо указания в поле Parameters пути (SFiIePath) задайте путь к каталогу, в который вы распаковали справочные файлы JDK. Проверьте, что вы ссылаетесь на файл Index. html, Который является старто­вой страницей всей справочной системы JDK. При запуске Internet Explorer или KDE Konqueror из меню JBuilder эти браузеры теперь появятся с готовой к просмот­ру документацией JDK. Переключаться между браузером и JBuilder можно с помо­щью комбинации клавиш Alt+Tab.

примечаниеЕсли вы работаете с JBuiIder 7, Но используете в качестве платформы разработки JDK Java 1.4, То с помощью этой техники вы можете легко "интегрировать" В IDE Javadoc-документацию.

Работа с Javadoc из командной строки

JBuilder позволяет быстро документировать код с помощью Javadoc. Если вы за­пускаете утилиту Javadoc из командной строки, придется немного больше пово­зиться с клавиатурой, но в этом случае вы также можете сгенерировать с помощью Javadoc соответствующие комментарии. Вы можете использовать эту технику для ав­томатизации процесса сборки проекта с помощью пакетных файлов или сценариев. Вы также можете работать из командной строки, если имеете дело с JBuilder редак­ции Personal.

Все опции, доступные в JBuilder, доступны и в режиме командной строки. На са­мом деле, если вы посмотрите в панели сообщений на выходные данные Javadoc, вы увидите, что JBuilder просто запускает средство Javadoc компании Sun

При работе в режиме командной строки придерживайтесь следующей базовой формулы:

Javadoc — d [каталог_назначения] -Sourcepath [исходный_каталог] имя_пакета

Каталог_наэначения — Это каталог, в котором нужно сохранить ваши Javadoc — файлы. Исходный_каталог — Это имя каталога, где находятся ваши исходные Java — файлы. Имя_пакета — Это корневой каталог пакета, в котором должна начинаться ваша документация.

Чтобы задать исходный каталог для вашей Javadoc-документации, вы можете либо изменить соответствующий каталог, либо ввести параметр -sourcepath Для за­дания пути к пакету или классу, который вы хотите документировать. Например, если вы находитесь на диске C и хотите документировать пакет Myproject, Находя­щийся в каталоге E:\personai\test\src, И поместить выходные HTML-файлы в каталог E:\personal\test\docs, То командная строка будет выглядеть следующим образом:

Javadoc — d e:\personal\test\docs — sourcepath e:\personal\test\src myproject

Если бы вы находились в каталоге E:\personal\test И хотели документировать файлы в подкаталоге docs, то можно было бы указать не абсолютный, а относитель­ный путь. Например, командная строка могла бы выглядеть так:

E:\personal\test> javadoc — d docs -sourcepath src myproject

Можно документировать и один файл из пакета. В этом случае параметр -sourcepath Не нужен. Вместо него потребуется задать относительный или абсо­лютный путь к тому файлу, который вы хотите документировать:

Javadoc — d docs srcMyprojectVApplicationl. java

Если вы хотите документировать более одного файла, можно просто добавить имя дог олнительного файла к существующей командной строке.

На шаге 3 мастера создания Javadoc-документации вы выбирали другие опции командной строки, в том числе минимальную видимость для документа: Public, Package, Protected или Private. Эти переключатели соответствуют опциям, которые в КОМаНДНОЙ Строке МОГУТ быть Записаны KaK — public, — package, — protected И -private. Шаг 4 мастера предоставляет дополнительные опции для дескрипторов и опций командной строки. Чтобы задать одну из них в командной строке, нужно по­местить ее после другой введенной информации. Например:

ɔavadoe — d docs srcMyprojectFramel. java — package

А вот пример команды, использующей обзорный файл:

Javadoc — d doc — package — sourcepath src — overview arc /overview. htnɪl breakouts

Резюме

B данной главе вы узнали, как комментировать свой код и автоматически созда­вать документацию с помощью утилиты Javadoc. Я потратил на эту тему немало вре­мени по двум причинам:

■ Я считаю, что комментирование кода исключительно важно. Тысячи про­граммистов по всему миру получают код от других разработчиков. Эти про­граммисты выполняют очень трудную задачу. Каждый день задержки сдачи их работы обходится их нанимателям в сотни или, чаще, в тысячи долларов. Очень немногие вещи могут помочь в этой ситуации настолько сильно, как надлежащая документация исходного кода.

■ Утилита Javadoc предоставляет очень полезные средства для документирова­ния разработанного кода. Если вы понимаете, как пользоваться ею, вы може­те сэкономить себе и другим немало времени и усилий.

Заставить программиста документировать свой код — все равно, что заставить ре­бенка принять горькое лекарство: большинство детей не любят это делать. Но Javadoc на самом деле является весьма привлекательной системой. Если вы понима­ете, как она работает, использование ее может превратиться в очень приятное заня­тие.

Чарли Калверт

Глава 22

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *