Java комментарии javadoc


Содержание

Javadoc

1. Что такое Javadoc?

Наибольшая проблема, связанная с документированием кода – поддержка этой документации. Если документация и код разделены, возникают трудности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации всякий раз при изменении программного кода. Среда разработки предлагает решение – связать код с документацией, поместив всё в один файл.

Javadoc — генератор документации в HTML-формате из комментариев исходного кода на Java.

Комментарии документации применяют для документирования:

  • классов,
  • интерфейсов,
  • полей (переменных),
  • конструкторов,
  • методов,
  • пакетов.

В каждом случае комментарий должен находиться перед документируемым элементом.

Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования.

НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.

Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется).

Дескрипторы, начинающиеся с фигурной скобки, например <@code>, называются встроенными и могут применяться внутри описания.

Java Документация Комментарии

Java аннотации только три вида способов. Первые два из них // и / * * /, а третья называется легендой комментарий, который начинается с / **, заканчиваются * /.

Описание Комментарий позволяет вставлять информацию о программе в программе. Вы можете использовать инструмент Javadoc для получения информации и вывод в HTML-файлах.

Описание Комментарий, вы записать больше информации о вашей программе.

Javadoc теги

Javadoc инструмент распознает следующие теги:

этикетка описание пример
@author Определяет класс авторов @author описание
@deprecated Названный членом класса или истек @deprecated описание
Путь, указанный в текущем документе корневой каталог Путь к каталогу
@exception Пометка исключения класса брошенные Исключение имя @exception объяснение
Непосредственно из родительского класса наследует комментарий Inherits комментарий от немедленного surperclass.
Вставка ссылки на другую тему
Вставьте ссылку на другую тему, но ссылка отображается в виде обычного текста шрифта Вставляет ссылку в линию на другую тему.
@param Описание параметра метода имя-параметра @param объяснение
@return Возвращаемый тип Описание @return информация
@see Определяет ссылку на другую тему @see якорь
@serial Описание последовательности собственности @serial описание
@serialData Описание Метод написанный writeObject () и writeExternal () данные описание @serialData
@serialField Описание компонентов ObjectStreamField @serialField описание типа имя
@since При введении специфического маркера изменения релиз @since
@throws И @exception же метка. @throws Тег имеет то же значение, что и @exception тега.
Дисплей значение константы, константа должна быть статическое свойство. Отображает значение константы, которое должно быть статическое поле.
@version Версия указанного класса @version информация

Документация Комментарии

После старта / **, первая линия или линии является основным описание классов, переменных и методов.

После этого, вы можете включать в себя один или несколько из какого рода @ тега. @ Каждый тег должен быть на новой строке, или начать в начале строки со звездочкой (*).

Множество того же типа этикетки должны быть помещены в группу. Например, если у вас есть три @see теги, они могут быть объединены по одному.

Ниже приводится описание примера класса комментарий:

Какой же выход Javadoc

Javadoc инструмент исходный код вашей программы Java в качестве входных данных, вывод некоторых HTML-файл, содержащий вашу программу аннотаций.

Каждый тип информации будет один в HTML-файле. Выход Javadoc также может быть унаследован дерево и индексы.

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

примеров

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

IT Novella

Javadoc — стандартный генератор документации в HTML-формате из комментариев исходного кода.

Для создания описания к элементу(поле, класс, метод) используются специальный комментарий, расположенный выше этого элемента:


Для документирования можно использовать дескрипторы, вот некоторые из них: @author — автор @version — версия @since — указывает с какой версии появился этот блок кода @see — ссылка на другое место в документации @param — передаваемый параметр методу @return — описание возвращаемого значения метода @exception и @throws — описание исключений @deprecated — документирование устаревших частей кода — создание ссылки, можно вставлять в любое место — описание значения переменной

Как видно, в документации можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и через символ «#» его метод или поле.

Вот пример использования ссылок для документирования перегруженного конструктора:

На выходе получаем:

Пример документации конструктора

Чтобы увидеть документацию в eclipse выделите элемент и нажмите F2.

Java комментарии javadoc

Wikimedia Foundation . 2010 .

Смотреть что такое «Javadoc» в других словарях:

JavaDoc — ist ein Software Dokumentationswerkzeug, das aus Java Quelltexten automatisch HTML Dokumentationsdateien erstellt. Javadoc wurde ebenso wie Java von Sun Microsystems entwickelt und ist seit Version 2 ein Bestandteil des Java Development Kits. Die … Deutsch Wikipedia

Javadoc — ist ein Software Dokumentationswerkzeug, das aus Java Quelltexten automatisch HTML Dokumentationsdateien erstellt. Javadoc wurde ebenso wie Java von Sun Microsystems entwickelt und ist seit Version 2 ein Bestandteil des Java Development Kits. Die … Deutsch Wikipedia

Javadoc — is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code. The doc comments format used by Javadoc is the de facto industry standard for documenting Java >Wikipedia

Javadoc — est un outil développé par Sun Microsystems permettant de créer une documentation d API en format HTML depuis les commentaires présents dans un code source en Java. Javadoc est le standard industriel pour la documentation des >Wikipédia en Français

Javadoc — es una util >Wikipedia Español

Javadoc — Javadoc, OpenDoc … Universal-Lexikon

javadoc — Java Document Generator http://www.desy.de/cgi bin/man cgijavadoc zur Dokumentationserstellung des selbst geschriebenen Codes … Acronyms

javadoc — Java Document Generator (http://www.desy.de/cgi bin/man cgijavadoc) zur Dokumentationserstellung des selbst geschriebenen Codes … Acronyms von A bis Z

Java Platform, Standard Edition — or Java SE is a w >Wikipedia

Java (programming language) — infobox programming language name = Java paradigm = Object oriented, structured, imperative year = 1995 designer = Sun Microsystems latest release version = Java Standard Edition 6 (1.6.0) latest release date = latest test version = latest test… … Wikipedia

Мне нужно задокументировать ЭТО?

Благо и бремя интегрированной документации а ля Javadoc

Серия контента:

Этот контент является частью # из серии # статей: Теория и практика Java

Этот контент является частью серии: Теория и практика Java

Следите за выходом новых статей этой серии.

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

Обучение от Javadoc

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

Большинство Java-пакетов имеют какой-либо «корневой» объект, первый объект, который вам необходимо создать, прежде чем вы сможете добраться до любого другого объекта этой функции. В JNDI данный корневой объект — это Context , а в JMS и JDBC — это Connection . Если бы кто-нибудь сказал вам, что фундаментальный объект в JDBC — это Connection , и объяснил, как его получить, вы могли бы узнать из Javadoc, как затем создать и выполнить Statement и выполнить итерацию полученного ResultSet путем внимательного прочтения списка доступных методов в Javadoc. Но как узнать, что первым вашим действием было получение Connection ? Javadoc организует классы в пакете и методы в классе в алфавитном порядке. К сожалению, не существует волшебного знака «Start Here (Начинать Здесь)» в Javadoc для привлечения читателей к логическому месту начала, с которого надо исследовать API.

Описание пакета

Наибольшим приближением к знаку «Start Here (Начинать Здесь)» является описание пакета, но оно редко когда используется эффективно. Если вы разместите файл package.html с исходным кодом для пакета, стандартный doclet положит содержимое в сгенерированный файл package-summary.html вместе с перечнем классов в данном пакете. К сожалению, стандартный doclet, выпускающий HTML документацию, которую мы все знаем, не позволяет легко найти описание пакета. Когда вы нажимаете на пакет в верхнем левом окне, то оно выдает список метода в нижнем левом окне, но не выводит резюме пакета в основном окне — вам придется нажать на имя пакета в нижнем левом окне, чтобы его увидеть. Но как бы там ни было, большинство пакетов не имеют описания.

Документация пакета является прекрасным местом для размещения документации «Start Here» в качестве обзора того, что пакет делает, каковы ключевые абстрактные конструкции, и с чего следует начинать изучать Javadoc-пакета.

Документация класса


Кроме документации пакета, документация классов также может значительно помочь пользователю перемещаться по новой функции. Документация классов должна, конечно же, включать описание того, что выполняет именно этот класс, но также и описание того, как этот класс соотносится с другими классами пакета, и в особенности идентифицировать любые значимые фабричные (factory) классы для данного класса. Например, документация для класса Statement в JDBC должна объяснять, что Statement получается с помощью метода createStatement() класса Connection . Таким образом, если новый пользователь имеет затруднения на странице Statement , он может узнать, что сначала ему необходимо получить Connection . Пакет, использующий это условное обозначение для каждого класса, быстро укажет пользователю на корневой объект, и пользователь сможет разобраться.

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

Плохая документация == плохой код

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

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

Написание Javadoc является формой просмотра кода

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

Возможности самопромотра документации говорят об особой важности написания Javadoc на раннем этапе процесса разработки, а затем ее периодического обзора по мере развития кода, вместо того, чтобы просто дожидаться завершения кода, и только затем писать документацию (если на это останется время). При такой стратегии, которая весьма распространена, написание документации откладывается до финальной стадии проекта, когда графики поджимают, и сотрудники перегружены работой. И в результате мы слишком часто получаем бесполезную документацию, показанную в Листинге 1, которая создает лишь «иллюзию документации.» В ней не сообщается ничего действительно необходимого пользователю, никаких сведений о том, как работает данный класс.

Листинг 1. Типичная бесполезная Javadoc

Из чего же должна состоять хорошая документация?

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

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

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

Правила Javadoc предоставляют тег @param , позволяющий нам задокументировать то, что означает параметр, в дополнение к его имени и типу. Тем не менее, не все методы соглашаются принять любое значение параметра. Например, в случае, когда допустимо передать нулевое значение (null) любому методу, принимающему параметр объекта без нарушения правил контроля типа, не все методы мягко соглашаются принять нулевое значение. В Javadoc должен быть ясно описан допустимый диапазон значений для параметров; если ожидается, что параметр будет не нулевым, то это должно быть указано, и если ожидаемые значения определенной области, такие как строки определенной длины или целые числа больше ноля, то это тоже должно быть указано. Не все методы тщательно проверяют свои параметры на предмет соответствия; отсутствие проверок соответствия и документации по множеству допустимых вводов запросто могут привести вас к аварийной ситуации.

Коды возврата

Javadoc позволяет легко описать возвращаемое значение, но, как и с параметрами метода, тег @return должен включать подробное описание множества значений, которые могут быть возвращены. Для типов возврата значения объекта будет ли когда-либо выдаваться ноль? Для типов возврата значения целого числа ограничивается ли результат набором известных или неотрицательных значений? Имеют ли какие-либо коды возврата особое значение, как, например, возврат -1 из java.io.InputStream.read() для обозначения конца файла? Используется ли код возврата для обозначения ситуации ошибки, как, например, возврат ноля в случае, если запись в таблице не может быть найдена?

Исключения

Стандартный doclet дублирует конструкцию throws метода, но Javadoc-теги @throws должны быть гораздо более конкретными. Например, NoSuchFileException является подклассом IOException , но большинство методов в java.io декларируются только для выброса IOException . Тем не менее, знание того, что метод может выбросить NoSuchFileException отдельно от других IOException является полезным для вызывающего — и этот метод должен быть включен в Javadoc. Также вы должны указать фактическую ситуацию ошибки, при которой будут выбрасываться различные классы исключений так, чтобы вызывающий знал, какое корректировочное действие предпринять в случае выброса данного исключения. Вы должны задокументировать каждое отмеченное и неотмеченное исключение, которое может выбросить метод, с помощью тега @throws , и задокументировать условия, при которых это исключение будет выброшено.

Входные условия, выходные условия и инварианты

Конечно, вы должны задокументировать влияние метода на состояние объекта. Но вы можете захотеть пойти дальше и описать входные условия метода, выходные условия и инварианты класса. Входное условие (precondition) является ограничением состояния объекта до вызова метода; например, входным условием вызова Iterator.next() является истинность hasMore() . Выходным условием (postcondition) является ограничение состояния объекта после завершения вызова метода, так List не является пустым после вызова add() . Инвариантом является ограничение состояния объекта, которое всегда действует постоянно, как Collection.size() == Collection.toArray().length() .

Инструменты Design-by-contract, такие как jContract, позволяют вам указывать входные условия, выходные условия и инварианты класса, используя специальные комментарии, а затем инструменты генерируют дополнительный код для применения данных ограничений. Используете вы инструмент или нет для обеспечения данных вероятностей, документирование этих ограничений дает пользователям представление о том, что они могут безопасно сделать с классом.

Побочные эффекты

Иногда метод дает побочные эффекты, отличные от изменений состояния объекта, такие как изменения состояния взаимосвязанных объектов, JVM или базовой компьютерной платформы. Например, все методы, выполняющие I/O, имеют побочные эффекты. Некоторые побочные эффекты вполне безвредны, например, хранение сведений о количестве запросов, обработанных классом. Другие имеют значительное влияние на производительность и точность программы, как например модифицирование состояния объекта, передаваемого методу, или хранение копии ссылки на этот объект. Такие побочные эффекты как модифицирование состояния взаимосвязанных объектов или хранение ссылок на объекты, переданные как параметры метода, должны быть задокументированы.

Связывание (linkage) метода

Связывание метода означает, что два метода в классе опираются друг на друга и определяют поведение друг друга. Типичной ситуацией, когда это происходит, является тот случай, когда метод внутренне использует метод toString того же класса, и предполагает, что toString особым образом задаст формат состояния объекта. Данная ситуация может вызвать проблемы, если класс имеет подклассы, а метод toString отменен; другой метод внезапно прекратит корректное функционирование, если он сам не отменен (overridden). Если ваши методы опираются на способы реализации других методов, то необходимо задокументировать эти зависимости. Затем, если класс имеет подклассы, оба метода могут быть отменены соответствующим образом так, что подкласс все еще будет функционировать должным образом.

Безопасность потока

Одно из наиболее важных способов поведения, который вы должны задокументировать — и чего почти никогда не бывает — это безопасность потока. Является ли этот класс поточно-безопасным? Если нет, можно ли сделать его поточно-безопасным, упаковывая вызовы при помощи синхронизации? Должны ли эти синхронизации быть взаимосвязаны с конкретной программой-монитором, или подойдет любой монитор, использующийся согласованно? Вызывают ли методы блокировки объектов, видимых извне класса?

Безопасность потока в действительности не есть что-то бинарное; имеются несколько распознаваемых степеней безопасности потока. Задокументировать безопасность потока, или даже определить степень безопасности потока, не всегда легко. Но невозможность сделать это может привести к серьезным проблемам; использование поточно-небезопасных классов в текущих приложениях может вызвать спорадические неисправности, которые часто не проявляются до ввода в действие (когда приложение подвергается нагрузке). А надстройка дополнительной блокировки вокруг уже поточно-безопасных классов может повредить производительности и даже может вызвать взаимоблокировку.

В своей книге, Справочник по эффективному программированию на языке Java (см. Ресурсы) Джош Блох предлагает полезную таксономию для документирования степеней безопасности потока класса. Классы могут быть классифицированы по следующим группам, в порядке снижения безопасности потока: неизменяемые, поточно-безопасные, условно поточно-безопасные, поточно-совместимые, и поточно-неблагоприятные.

Данная классификация является отличной средой для сообщения существенной информации о поведении класса в случае параллельного доступа. Не имеет значения, используете ли вы именно эту таксономию или нет, но вы безусловно должны идентифицировать степень безопасности потока, на которую рассчитан ваш класс. Я бы также предложил, что если метод вызывает блокировку объекта, видимого извне кода класса, следует это задокументировать, даже если это только «деталь реализации,» для того, чтобы содействовать принятию решений о порядке глобальной блокировки и предотвращению взаимоблокировки.

Выводы

Документирование поведения класса это не просто краткое описание того, что делает каждый метод. Эффективная Javadoc должна содержать описания того:


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

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

Ресурсы для скачивания

Похожие темы

  • Оригинал статьи: I have to document THAT?.
  • В руководстве Sun «Как написать Doc Comments для инструмента Javadoc» описываются правила и философия Javadoc.
  • Джош Блох (Josh Bloch) в Справочнике по эффективному программированию на языке Java делится множеством советов и методик по написанию лучшего кода.
  • JContract является коммерческим инструментом для увеличения взаимодействия и ограничений классов .
  • В статье «Особые методики» (JavaWorld, август 2001 г.) предлагаются рекомендации по написанию конструкций throws .
  • Джереми Рошель (Jeremy Roschelle) в статье «Doclet your servlet» (JavaWorld, март 2001 г.) описывается то, как вы можете использовать пользовательские doclets для получения еще более подробной документации для сервлетов.
  • Джон Фаррелл (John Farrell) рассуждает о важности Javadoc в рефакторинге Java-классов в «Сделайте плохой код хорошим» (JavaWorld, март, 2001).
  • Скотт Амблер (Scott Ambler) предлагает удобную таблицу контрольных проверок для методов документирования (developerWorks, август 2000 г.).
  • Интенсификатор документации для Java от IBM alphaWorks является инструментом, совершенствующим файлы Javadoc, путем дополнения их новой информацией (семантической информацией, сортировкой и управляемостью), которая собирается с помощью статического анализа соответствующих файлов Java-класса.
  • Javadoc doclet API позволяет Вам написать пользовательские плагины Javadoc для получения различных видов документации, или даже автогенерирующего кода или схемы по комментариям Javadoc.
  • Прочтите всю серию Теория и практика Java.
  • Сотни ресурсов по Java-технологии в разделе Java-технологииdeveloperWorks.

Комментарии

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

Javadoc — Javadoc

Javadoc (первоначально обсаженные JavaDoc ) представляет собой генератор документации , созданный Sun Microsystems для языка Java ( в настоящее время принадлежит корпорации Oracle ) для создания API документации в HTML формате из Java исходного кода. Формат HTML используется для добавления удобства возможности гиперссылке соответствующих документы вместе.

Формат «Doc комментарии» , используемый Javadoc является де — факто отраслевым стандартом для документирования классов Java. Некоторые Иды , как IntelliJ IDEA , NetBeans и Eclipse , автоматически генерировать Javadoc HTML. Многие редакторы файлов помочь пользователю в создании источника Javadoc и использовать информацию Javadoc как внутренние ссылки для программиста.

Javadoc также предоставляет API для создания доклетов и taglets, что позволяет пользователям анализировать структуру приложения Java. Это как JDiff может генерировать отчеты о том, что изменилось между двумя версиями в API.

Javadoc не влияет на производительность в Java, поскольку все комментарии удаляются во время компиляции. Написание комментариев и Javadoc для лучшего понимания кода и, таким образом, лучше поддерживать ее.

содержание

история

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

Javadoc была использована Java с первого выпуска, и обычно обновляется при каждом новом выпуске комплекта Java Development Kit .

Техническая архитектура

Структура Javadoc комментарий

Javadoc комментарий оттеняется из кода с помощью стандартных многострочного комментария тегов /* и */ . Открывающий тег ( так называемый начать-комментарий разделителем), имеет дополнительную звездочку, как и в /** .


  1. Первый абзац представляет собой описание метода документально.
  2. После описания является переменным числом описательных тегов, означающий:
    1. Параметры метода ( @param )
    2. То , что метод возвращает ( @return )
    3. Любые исключения метод может бросить ( @throws )
    4. Другие менее общие теги , такие как @see (тег «смотри также»)

Обзор Javadoc

Основная структура написания комментариев документа является встраивать их внутрь /** . */ . Javadoc записывается рядом с элементами без каких — либо разделяющей новой строки. Обратите внимание , что любые операторы импорта должны предшествовать объявление класса. Объявление класса , как правило , содержит:

Для методов есть (1) краткое, краткое, описание одна строка , чтобы объяснить , что делает этот пункт. За этим следует (2) Более полное описание , которое может охватывать несколько пунктов. Детали могут быть объяснены в полном объеме здесь. Этот раздел является необязательным. Наконец, есть (3) раздел тега в список принятых входных аргументов и возвращаемые значения метода. Обратите внимание , что все Javadoc рассматривается как HTML , так что несколько разделов абзаца разделяются «

Переменные описаны аналогично методам, за исключением, что часть (3) опущена. Здесь переменная содержит только краткое описание:

Обратите внимание, что не рекомендуется определить несколько переменных в одной документации комментарий. Это происходит потому, что Javadoc читает каждую переменную и помещает их отдельно сгенерированной HTML страницы с той же документации комментарий, который копируется для всех полей.

Вместо этого рекомендуется писать и документировать каждую переменную отдельно:

Таблица Javadoc теги

Некоторые из доступных тегов Javadoc, перечислены в таблице ниже:

Tag & Parameter использование Относится к поскольку
@author John Smith Рассказывает автор. Класс, интерфейс, Enum
< @DocRoot > Представляет относительный путь к корневой директории сгенерированного документа из любой сгенерированной страницы. Класс, интерфейс, Enum, поле, метод
@version версия Обеспечивает запись версии программного обеспечения. Макс один за класс или интерфейс. Класс, интерфейс, Enum
@since так-текст Описывает, когда эта функциональность первого существовала. Класс, интерфейс, Enum, поле, метод
@see ссылка Обеспечивает связь с другим элементом документации. Класс, интерфейс, Enum, поле, метод
@param название описание Описывает параметр метода. метод
@return описание Описывает возвращаемое значение. метод
@exception описание имя_класса
@throws описание Classname
Описывает исключение, которое может быть выброшено из этого метода. метод
@deprecated описание Описывает устаревший метод. Класс, интерфейс, Enum, поле, метод
< @InheritDoc > Копирование описание из переопределенного метода. Перекрытие Метод 1.4.0
< @Link ссылка > Ссылка на другой символ. Класс, интерфейс, Enum, поле, метод
< @Linkplain ссылка > Идентичный <@link>, кроме наклейке Линка отображается в виде обычного текста, чем код шрифта. Класс, интерфейс, Enum, поле, метод
< @Value #STATIC_FIELD > Возвращает значение статического поля. Статическое поле 1.4.0
< @Code буквальным > Форматы буквальный текст в коде шрифта. Это эквивалентно <@ буквального>. Класс, интерфейс, Enum, поле, метод 1.5.0
< @Literal буквальным > Обозначает буквальный текст. Прилагаемый текст интерпретируется как не содержащий HTML-разметку или вложенные теги JavaDoc. Класс, интерфейс, Enum, поле, метод 1.5.0
< @Serial буквальным > Используется в доке комментарии для сериализуемого поля по умолчанию. поле
< @SerialData буквальным > Документы данные, записанные с помощью writeObject () или writeExternal () методы. Поле, метод
< @SerialField буквальным > Документы компонент ObjectStreamField. поле

Примеры

Пример Javadoc к документу метод следующим образом. Обратите внимание на то, что интервал и количество символов в этом примере, как конвенции государства.

Документирование javadoc. Сценарии ant и javadoc

В стандартной библиотеке существует огромное количество классов и методов, запомнить которые невозможно. Поэтому для нахождения информации о конкретном методе или классе необходимо пользоваться оперативной документацией интерфейса API. Документация интерфейса API является составной частью набора инструментальных средств Java SDK и создана в HTML формате. Для каждой новой версии JDK имеется собственная документация, которую можно скачать по адресу http://java.sun.com в разделе Download. Кроме API в документации также можно найти следующую информацию (рис. 1):
— инструментальные средства и их опции запуска (каталог tools);
— описание различных языковых средств и технологий, которые составляют ядро Java (каталог guide).

Рисунок 1 — Структура каталога с документацией к Java.

Открыть документацию по интерфейсам классам или методам языка можно через файл docs/api/index.html. Окно документации разделено на три фрейма. В маленьком фрейме в правом углу приведены все доступные пакеты. Все пакеты можно увидеть также и в основном окне, щелкнув мышью на ссылке Overwiev в верхней строке основного окна. В правом нижнем фрейме перечислены все классы. Если щелкнуть кнопкой мыши на конкретном имени класса, то будет показана соответствующая документация по этому классу в основном окне.

Например, чтобы получить информацию о методах класса String, прокрутите левое нижнее окно, пока не увидите ссылку String. Щелкните на ней.

В основном окне для класса можно увидеть после его названия дерево наследования (рис. 2). Например, для класса String:

java.lang.Object
|_ java.lang.String

Рисунок 2 — Описание класса String.

Далее, как правило, следует перечисление интерфейсов, которые имплементирует данный класс. После этого следует описание назначения класса. Ниже следуют таблицы с кратким описанием полей, конструкторов и методов класса (рис. 3). Щелкните мышью на имени этого метода, чтобы получить его детальное описание. Например, если вы щелкните мышью на ссылке charAt , то получите полное описание метода charAt .

Рисунок 3 — Сводка методов класса String.

Если напротив метода вы увидите запись Deprecated , то использование данного метода нежелательно в данной версии JDK. Это означает, что данный метод может не во всех случаях отрабатывать корректно, либо создан альтернативный метод, который более эффективен.

Кроме ссылки Overwiev в верхней строки основного окна присутствуют также еще несколько полезных ссылок: Tree, Deprecated, Index, Help. С помощью ссылки Tree можно отобразить полное дерево наследования классов. С помощью ссылки Tree можно увидеть список всех нежелательных методов. С помощью ссылки Index можно легко найти класс, метод или интерфейс, зная только его имя. С помощью ссылки Help можно подробно ознакомиться с организацией и функционированием API.

Ссылки:

  1. Хорстман К.С., Корнелл Г. Библиотека профессионала. Java 2. Том 1. Основы. — М.: Издательский дом Вильямс, 2003. — 848 с.
  2. JavaTM 2 Platform Standard Edition 5.0 API Specification. http://java.sun.com

There are good reasons for making your own local javadocs, and it»s not particularly difficult!


First you need the source. At the time of writing the Java 8 JDK comes with a zip file called src.zip . Sometimes, for unexplained reasons, Oracle don»t always include the source. So for some older versions (and who knows about the future) you have to get hold of the Java source in another way. It»s worth also being aware that, in the past, Oracle have sometimes included the source with the Linux version of the JDK, but not with the Windows one.

I just unzipped this file. the top directories are «com», «java», «javax», «launcher» and «org». Directory launcher contains no files to document.

You can generate the javadocs very very simply from any or all of these by CD»ing at the command prompt/terminal to the directory . \src . Then go

javadoc -d docs -Xmaxwarns 10 -Xmaxerrs 10 -Xdoclint:none -sourcepath . -subpackages java:javax:org:com

NB note that there is a «.» after -sourcepath

Simple as that. Generating your own javadocs also has 2 huge advantages

  1. you know they are precisely the right javadocs for the JDK (or any exernal jar file) you are using on your system
  2. once you get into the habit, reconstituting your Javadocs is not a tiresome challenge (i.e. where to go looking for them). For example I just unzipped a couple of source jars whose packages are closely coupled, so their sources were in effect «merged» & then made a single Javadoc from them.

NB Swing is semi-officially DEAD. We should all be switching to JavaFX, which is helpfully bundled with Java 8 JDK, but in its own source file, javafx-src.zip .

Unzipped, this reveals 3 «root» packages: com , javafx and netscape (wha»?). These should be manually moved over the to appropriate places under the unzipped src directory (including the JavaFX com.sun packages under the Java com.sun strcture). Compiling all these Javadoc files took my machine a non-negligible time. I»d expect to see all the JavaFX source classes in with all the other source classes some time soon.

BTW, the same thinking applies to documenting any and all Java jars (with source) which you use. However, all versions of most jars will be found with their documentation available for download at Maven Central http://search.maven.org .

PS afterthought:
using Eclipse and the «Gradle STS» plugin: the «New Gradle STS Project» wizard will create a gradle.build file containing the line

This magically downloads the source jar with the executable jar (under GRADLE_HOME) when you go

Giving you an extra degree of certainty that you have got the right src and therefore the right javadoc for the dependency in question.

Eclipse не вытягивает всплывающие подсказки из местоположения javadoc. Он использует только расположение javadoc для добавления к ссылке, если вы говорите, что открыто в браузере, вам нужно загрузить и прикрепить источник для JDK, чтобы получить всплывающие подсказки. Для всех JAR под JRE у вас должно быть следующее для местоположения javadoc: http://java.sun.com/javase/6/docs/api/ . Для resources.jar, rt.jar, jsse.jar, jce.jar и charsets.jar вы должны приложить исходный доступный .

Чтобы использовать автономную документацию Java API в Eclipse, вам необходимо сначала загрузить ее. Ссылка на документы Java (последнее обновление: 2013-10-21):

  • Извлеките zip файл в ваш локальный каталог.
  • Из eclipse Window Preferences Java «Installed JREs» выберите доступную JRE (jre6: C:\Program Files (x86)\Java\jre6, например) и нажмите «Изменить».
  • Выберите все «Библиотеки систем JRE» с помощью Control + A .
  • Нажмите «Местоположение Javadoc»
  • Измените «путь местоположения Javadoc:» от » http://download.oracle.com/javase/6/docs/api/ » to «file:/E:/Java/docs/api/».

Он должен работать, поскольку он работает для меня. Мне больше не нужно подключение к Интернету для просмотра документации API Java в Eclipse.

Для автономного Javadoc из zip файла, а не для его извлечения.

Почему этот подход?

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

Сравнение zip файла и извлеченных данных.

57 MB after extracting this zip file —

Таким образом, этот подход экономит мои ок. 200 МБ.

Как использовать apidocs.zip?

2. Выберите jre из Installed JREs , затем нажмите Edit.

3.Выберите все.jar файлы из JRE system libraries , затем нажмите Javadoc Location.

4. Просмотрите файл apidocs.zip для Archive path и установите Path within archive , как показано выше. Что это.

5. Наведите курсор на любое имя класса или имя метода и нажмите Shift + F2

Старый вопрос, но у меня были текущие проблемы с этой проблемой. Поэтому я предоставляю вам мое решение. Теперь источники и javadocs находятся внутри jdk. Итак, разархивируйте версию jdk. Вы можете видеть, что contanins является файлом «src.zip». Вот ваши необходимые источники и файлы doc. Следуйте по пути: Window- > Preferences- > Java- > Установленные JREs- > выберите jre/jrd и нажмите «Изменить», Выберите все.jar файлы и нажмите Source Attachment. Выберите «Внешний файл. » и укажите его в файле src.zip.

Maibe необходим перезапуск в Eclipse. (обычно нет) Теперь вы должны увидеть документы, а также источники для классов из jdk.

Я столкнулся с той же проблемой, и я не нашел ответа на этот вопрос полезным, потому что они старые и с новым JDK 1.8, в разделе документации есть был перенесен в src.zip в папку JDK (C:\Program Files\Java\jdk1.8.0_101).


Теперь я попробовал все сверху, и он показывал мне ту же проблему, если я нажимаю ctrl и нажимаю (например, String или System) в своей программе, я получаю Источник не найден .

Теперь вы можете сделать это, перейдите в папку, где установлен JDK (C:\Program Files\Java\jdk1.8.0_101) , и попробуйте распаковать src.zip. Здесь вы можете столкнуться с проблемой как-то из-за административных прав в этой папке, это не позволит вам распаковать этот src.zip . Для решения проблемы скопируйте файл src.zip и вставьте его в любую другую папку (например, Desktop), а затем создайте папку src и разархивируйте ее. Теперь скопируйте эту папку обратно в папку JDK 1.8 ** (C:\Program Files\Java\jdk1.8.0_101). **

Теперь просто зайдите в eclipse и откройте любую программу и нажмите ctrl и нажмите на любые внешние объекты или что угодно (например, String или System). Вы получите Source not found, Now Нажмите Прикрепить источник → Внешнее местоположение → Внешняя папка и добавьте ваше местоположение src (C:\Program Files\Java\jdk1.8.0_101\src). Теперь вам хорошо идти, я пытался, и это сработало для меня.

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

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

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

Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc , который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.

javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.

При написании комментариев к кодам Java используют три типа комментариев:

// однострочный комментарий; /* многострочный комментарий */ /** комментирование документации */

С помощью утилиты javadoc , входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.

Дескрипторы javadoc , начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например , называются встроенными и могут применяться внутри описания.

Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.

javadoc дескрипторы: @author, @version, @since, @see, @param, @return

Дескриптор Применение Описание
@author Класс, интерфейс Автор
@version Класс, интерфейс Версия. Не более одного дескриптора на класс
@since Указывает, с какой версии доступно
@see Класс, интерфейс, поле, метод Ссылка на другое место в документации
@param Метод Входной параметр метода
@return Метод Описание возвращаемого значения
@exception имя_класса описание Метод
@throws имя_класса описание Метод Описание исключения, которое может быть послано из метода
@deprecated Класс, интерфейс, поле, метод Описание устаревших блоков кода
Класс, интерфейс, поле, метод Ссылка
Статичное поле Описание значения переменной

Форма документирования кода

Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.

В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа «@» должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

/** * Класс продукции со свойствами maker и price. * @autor Киса Воробьянинов * @version 2.1 */ >

Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.

Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.

Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.

Сценарии ant и javadoc

Для создания документации можно использовать ant .

Пример сценария (задания) ant для формирования документации к приложению MyProject:

Подробная информация формирования документации представлена на странице

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

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

  1. комментируя код Вы в последствии сможете быстро понять о чем идет речь, когда вернетесь к коду через некоторое время
  2. грамотные и понятные комментарии можно сразу оформлять в стиле javadoc. Затем по всем классам проекта можно автоматически сформировать документацию, если появится потребность выставить код на всеобщее обозрение. Таким образом, не придется тратить время на написание документации к проекту.

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

Итак, рассмотрим простейшую программу на Java, которая содержит комментарии:

/**
* Данный комментарий описывает класс MyrusakovApp
* текст комментария может располагаться на нескольких строках
*/
class MyrusakovApp <


/**
* Главный метод
*
* @return void — один из специальных маркер в javadoc для обозначения возвращаемого значения
*/
public static void main(String[] args) <
System.out.println(«Author: Myrusakov!»); // Однострочный комментарий — Отображает строку.
>
>

В Java существуют следующие виды комментариев:

/* простой текст. все что внутри игнорируется компилятором */

/**
* комментарий документации
*
* с помощью него создается комментарий документирования. Компилятор игнорирует все что находится внутри данного комментария
* Утилита javadoc использует этот тип комментариев для автогенерации документации. Необходимые параметры задаются с помощью
* специальных терминов
*
*/

// Просто однострочный комментарий, который распространяется до конца строки

Таким образом, комментарии — это очень важный и нужный инструмент, для использования которого надо просто выработать привычку, которая даст свои плоды в будущем.

Копирование материалов разрешается только с указанием автора (Михаил Русаков) и индексируемой прямой ссылкой на сайт (http://myrusakov.ru)!

Добавляйтесь ко мне в друзья ВКонтакте: http://vk.com/myrusakov.
Если Вы хотите дать оценку мне и моей работе, то напишите её в моей группе: http://vk.com/rusakovmy.

Если Вы не хотите пропустить новые материалы на сайте,
то Вы можете подписаться на обновления: Подписаться на обновления

Если у Вас остались какие-либо вопросы, либо у Вас есть желание высказаться по поводу этой статьи, то Вы можете оставить свой комментарий внизу страницы.

Порекомендуйте эту статью друзьям:

Если Вам понравился сайт, то разместите ссылку на него (у себя на сайте, на форуме, в контакте):

Она выглядит вот так:

  • BB-код ссылки для форумов (например, можете поставить её в подписи):
  • Комментарии ( 0 ):

    Для добавления комментариев надо войти в систему.
    Если Вы ещё не зарегистрированы на сайте, то сначала зарегистрируйтесь.

    Copyright © 2010-2020 Русаков Михаил Юрьевич. Все права защищены.

    Java комментарии javadoc

    73 просмотра

    1 ответ

    528 Репутация автора

    Я читаю много статей о Javadoc, но все еще не могу управлять, когда начинается «шаблон». В этом примере:

    Могу ли я выполнить их как-нибудь, чтобы они были менее шаблонными, или я должен просто удалить их?

    Почему в 75% статей, называемых «лучшие практики для Javadoc», есть повторения? Например:

    Разве это не пишет 2 раза одно и то же?

    Ответы (1)

    8 плюса

    106027 Репутация автора

    В определенной степени это касается «стиля». Тем не менее, давайте посмотрим:

    Некоторые люди утверждают, что есть определенная заслуга


    • удобочитаемое описание, которое говорит вам, что делает метод
    • дополнительная информация с использованием тегов @param / @return

    Например, вы можете переписать это так:

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

    Но, как уже было сказано, в конце концов, это вопрос стиля, и ключевой момент заключается в следующем: вы должны выбрать тот «стиль», который вы (и ваши коллеги) посчитаете наиболее полезным для вашего контекста.

    И обратите внимание: вместо того, чтобы повторять «очевидные» вещи снова и снова, более полезный комментарий может выглядеть так:

    Который в основном «мой» предпочтительный стиль — идти с одной строкой @return. Но вместо этого упомяните важные аспекты, такие как — этот метод генерирует это исключение времени выполнения, если .

    Последнее замечание: наличие «пустых» строк @param (которые дают только имя параметра) — явный запрет. Эти строки ничего вам не говорят, но вам все равно придется тратить время на их чтение и игнорирование . Такие вещи бесполезны . Избегайте этого.

    Документирование javadoc. Сценарии ant и javadoc

    В стандартной библиотеке существует огромное количество классов и методов, запомнить которые невозможно. Поэтому для нахождения информации о конкретном методе или классе необходимо пользоваться оперативной документацией интерфейса API. Документация интерфейса API является составной частью набора инструментальных средств Java SDK и создана в HTML формате. Для каждой новой версии JDK имеется собственная документация, которую можно скачать по адресу http://java.sun.com в разделе Download. Кроме API в документации также можно найти следующую информацию (рис. 1):
    — инструментальные средства и их опции запуска (каталог tools);
    — описание различных языковых средств и технологий, которые составляют ядро Java (каталог guide).

    Рисунок 1 — Структура каталога с документацией к Java.

    Открыть документацию по интерфейсам классам или методам языка можно через файл docs/api/index.html. Окно документации разделено на три фрейма. В маленьком фрейме в правом углу приведены все доступные пакеты. Все пакеты можно увидеть также и в основном окне, щелкнув мышью на ссылке Overwiev в верхней строке основного окна. В правом нижнем фрейме перечислены все классы. Если щелкнуть кнопкой мыши на конкретном имени класса, то будет показана соответствующая документация по этому классу в основном окне.

    Например, чтобы получить информацию о методах класса String, прокрутите левое нижнее окно, пока не увидите ссылку String. Щелкните на ней.

    В основном окне для класса можно увидеть после его названия дерево наследования (рис. 2). Например, для класса String:

    java.lang.Object
    |_ java.lang.String

    Рисунок 2 — Описание класса String.

    Далее, как правило, следует перечисление интерфейсов, которые имплементирует данный класс. После этого следует описание назначения класса. Ниже следуют таблицы с кратким описанием полей, конструкторов и методов класса (рис. 3). Щелкните мышью на имени этого метода, чтобы получить его детальное описание. Например, если вы щелкните мышью на ссылке charAt , то получите полное описание метода charAt .

    Рисунок 3 — Сводка методов класса String.

    Если напротив метода вы увидите запись Deprecated , то использование данного метода нежелательно в данной версии JDK. Это означает, что данный метод может не во всех случаях отрабатывать корректно, либо создан альтернативный метод, который более эффективен.

    Кроме ссылки Overwiev в верхней строки основного окна присутствуют также еще несколько полезных ссылок: Tree, Deprecated, Index, Help. С помощью ссылки Tree можно отобразить полное дерево наследования классов. С помощью ссылки Tree можно увидеть список всех нежелательных методов. С помощью ссылки Index можно легко найти класс, метод или интерфейс, зная только его имя. С помощью ссылки Help можно подробно ознакомиться с организацией и функционированием API.

    Ссылки:

    1. Хорстман К.С., Корнелл Г. Библиотека профессионала. Java 2. Том 1. Основы. — М.: Издательский дом Вильямс, 2003. — 848 с.
    2. JavaTM 2 Platform Standard Edition 5.0 API Specification. http://java.sun.com

    There are good reasons for making your own local javadocs, and it»s not particularly difficult!

    First you need the source. At the time of writing the Java 8 JDK comes with a zip file called src.zip . Sometimes, for unexplained reasons, Oracle don»t always include the source. So for some older versions (and who knows about the future) you have to get hold of the Java source in another way. It»s worth also being aware that, in the past, Oracle have sometimes included the source with the Linux version of the JDK, but not with the Windows one.

    I just unzipped this file. the top directories are «com», «java», «javax», «launcher» and «org». Directory launcher contains no files to document.

    You can generate the javadocs very very simply from any or all of these by CD»ing at the command prompt/terminal to the directory . \src . Then go

    javadoc -d docs -Xmaxwarns 10 -Xmaxerrs 10 -Xdoclint:none -sourcepath . -subpackages java:javax:org:com

    NB note that there is a «.» after -sourcepath

    Simple as that. Generating your own javadocs also has 2 huge advantages

    1. you know they are precisely the right javadocs for the JDK (or any exernal jar file) you are using on your system
    2. once you get into the habit, reconstituting your Javadocs is not a tiresome challenge (i.e. where to go looking for them). For example I just unzipped a couple of source jars whose packages are closely coupled, so their sources were in effect «merged» & then made a single Javadoc from them.


    NB Swing is semi-officially DEAD. We should all be switching to JavaFX, which is helpfully bundled with Java 8 JDK, but in its own source file, javafx-src.zip .

    Unzipped, this reveals 3 «root» packages: com , javafx and netscape (wha»?). These should be manually moved over the to appropriate places under the unzipped src directory (including the JavaFX com.sun packages under the Java com.sun strcture). Compiling all these Javadoc files took my machine a non-negligible time. I»d expect to see all the JavaFX source classes in with all the other source classes some time soon.

    BTW, the same thinking applies to documenting any and all Java jars (with source) which you use. However, all versions of most jars will be found with their documentation available for download at Maven Central http://search.maven.org .

    PS afterthought:
    using Eclipse and the «Gradle STS» plugin: the «New Gradle STS Project» wizard will create a gradle.build file containing the line

    This magically downloads the source jar with the executable jar (under GRADLE_HOME) when you go

    Giving you an extra degree of certainty that you have got the right src and therefore the right javadoc for the dependency in question.

    Eclipse не вытягивает всплывающие подсказки из местоположения javadoc. Он использует только расположение javadoc для добавления к ссылке, если вы говорите, что открыто в браузере, вам нужно загрузить и прикрепить источник для JDK, чтобы получить всплывающие подсказки. Для всех JAR под JRE у вас должно быть следующее для местоположения javadoc: http://java.sun.com/javase/6/docs/api/ . Для resources.jar, rt.jar, jsse.jar, jce.jar и charsets.jar вы должны приложить исходный доступный .

    Чтобы использовать автономную документацию Java API в Eclipse, вам необходимо сначала загрузить ее. Ссылка на документы Java (последнее обновление: 2013-10-21):

    • Извлеките zip файл в ваш локальный каталог.
    • Из eclipse Window Preferences Java «Installed JREs» выберите доступную JRE (jre6: C:\Program Files (x86)\Java\jre6, например) и нажмите «Изменить».
    • Выберите все «Библиотеки систем JRE» с помощью Control + A .
    • Нажмите «Местоположение Javadoc»
    • Измените «путь местоположения Javadoc:» от » http://download.oracle.com/javase/6/docs/api/ » to «file:/E:/Java/docs/api/».

    Он должен работать, поскольку он работает для меня. Мне больше не нужно подключение к Интернету для просмотра документации API Java в Eclipse.

    Для автономного Javadoc из zip файла, а не для его извлечения.

    Почему этот подход?

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

    Сравнение zip файла и извлеченных данных.

    57 MB after extracting this zip file —

    Таким образом, этот подход экономит мои ок. 200 МБ.

    Как использовать apidocs.zip?

    2. Выберите jre из Installed JREs , затем нажмите Edit.

    3.Выберите все.jar файлы из JRE system libraries , затем нажмите Javadoc Location.

    4. Просмотрите файл apidocs.zip для Archive path и установите Path within archive , как показано выше. Что это.

    5. Наведите курсор на любое имя класса или имя метода и нажмите Shift + F2

    Старый вопрос, но у меня были текущие проблемы с этой проблемой. Поэтому я предоставляю вам мое решение. Теперь источники и javadocs находятся внутри jdk. Итак, разархивируйте версию jdk. Вы можете видеть, что contanins является файлом «src.zip». Вот ваши необходимые источники и файлы doc. Следуйте по пути: Window- > Preferences- > Java- > Установленные JREs- > выберите jre/jrd и нажмите «Изменить», Выберите все.jar файлы и нажмите Source Attachment. Выберите «Внешний файл. » и укажите его в файле src.zip.

    Maibe необходим перезапуск в Eclipse. (обычно нет) Теперь вы должны увидеть документы, а также источники для классов из jdk.

    Я столкнулся с той же проблемой, и я не нашел ответа на этот вопрос полезным, потому что они старые и с новым JDK 1.8, в разделе документации есть был перенесен в src.zip в папку JDK (C:\Program Files\Java\jdk1.8.0_101).

    Теперь я попробовал все сверху, и он показывал мне ту же проблему, если я нажимаю ctrl и нажимаю (например, String или System) в своей программе, я получаю Источник не найден .

    Теперь вы можете сделать это, перейдите в папку, где установлен JDK (C:\Program Files\Java\jdk1.8.0_101) , и попробуйте распаковать src.zip. Здесь вы можете столкнуться с проблемой как-то из-за административных прав в этой папке, это не позволит вам распаковать этот src.zip . Для решения проблемы скопируйте файл src.zip и вставьте его в любую другую папку (например, Desktop), а затем создайте папку src и разархивируйте ее. Теперь скопируйте эту папку обратно в папку JDK 1.8 ** (C:\Program Files\Java\jdk1.8.0_101). **

    Теперь просто зайдите в eclipse и откройте любую программу и нажмите ctrl и нажмите на любые внешние объекты или что угодно (например, String или System). Вы получите Source not found, Now Нажмите Прикрепить источник → Внешнее местоположение → Внешняя папка и добавьте ваше местоположение src (C:\Program Files\Java\jdk1.8.0_101\src). Теперь вам хорошо идти, я пытался, и это сработало для меня.

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

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

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

    Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc , который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.

    javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.

    При написании комментариев к кодам Java используют три типа комментариев:

    // однострочный комментарий; /* многострочный комментарий */ /** комментирование документации */

    С помощью утилиты javadoc , входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.

    Дескрипторы javadoc , начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например , называются встроенными и могут применяться внутри описания.

    Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.

    javadoc дескрипторы: @author, @version, @since, @see, @param, @return

    Дескриптор Применение Описание
    @author Класс, интерфейс Автор
    @version Класс, интерфейс Версия. Не более одного дескриптора на класс
    @since Указывает, с какой версии доступно
    @see Класс, интерфейс, поле, метод Ссылка на другое место в документации
    @param Метод Входной параметр метода
    @return Метод Описание возвращаемого значения
    @exception имя_класса описание Метод
    @throws имя_класса описание Метод Описание исключения, которое может быть послано из метода
    @deprecated Класс, интерфейс, поле, метод Описание устаревших блоков кода
    Класс, интерфейс, поле, метод Ссылка
    Статичное поле Описание значения переменной

    Форма документирования кода

    Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.

    В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа «@» должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

    /** * Класс продукции со свойствами maker и price. * @autor Киса Воробьянинов * @version 2.1 */ >

    Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.

    Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.

    Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.

    Сценарии ant и javadoc

    Для создания документации можно использовать ant .

    Пример сценария (задания) ant для формирования документации к приложению MyProject:

    Подробная информация формирования документации представлена на странице

    Илон Маск рекомендует:  Что такое код getkeystate
    Понравилась статья? Поделиться с друзьями:
    Кодинг, CSS и SQL