- Документирование javadoc
- javadoc дескрипторы : @author, @version, @since, @see, @param, @return
- Форма документирования кода
- Сценарии ant и javadoc
- 37. Java — Javadoc
- Содержание
- Что такое Javadoc?
- Пример 1
- Пример 2
- Теги Javadoc
- Пример
- IT Novella
- Android Studio — советы и хитрости | Для разработчика андроид-приложений
- Если вы никогда ранее не использовали Android Studio и не знакомы с интерфейсом IntelliJ IDEA , эта статья дает советы для повышения производительности, которые помогут вам начать работу с некоторыми из наиболее распространенных задач.
- Функции производительности
- Smart Rendering
- Визуализация растрового изображения в отладчике
- Фильтры в окне вывода сообщений
- Установка иерархии Activity
- Создание макетов
- Работа с IntelliJ IDEA
- Alt + Enter комбинация клавиш
- Ctrl + D комбинация клавиш
- Меню навигации
- Идентификация областей кода
- Внешние аннотации
- Использование XML и SQL
- Сворачивание кода
- Предварительный просмотр изображений и цвета
- Быстрая документация F1
Документирование javadoc
При документировании приложения необходима также поддержка документации программы. Если документация и код разделены, то непроизвольно создаются сложности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации при изменении программного кода.
Как правило, все существующие среды разработки 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 | Класс, интерфейс, поле, метод | Описание устаревших блоков кода |
| Класс, интерфейс, поле, метод | Ссылка | |
| Статичное поле | Описание значения переменной |
Форма документирования кода
Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.
В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа ‘@’ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.
Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.
Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.
Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.
Сценарии ant и javadoc
Для создания документации можно использовать ant.
Пример сценария (задания) ant для формирования документации к приложению MyProject :
Подробная информация формирования документации представлена на странице Javadoc/Javadoc2
Источник
37. Java — Javadoc
Язык Java поддерживает три типа комментариев:
| № | и описание |
| 1 | /* текст */ Компилятор игнорирует все от / * до * /. |
| 2 | //текст Компилятор игнорирует все от // до конца строки. |
| 3 | /** документация */ Это документационный комментарий. Инструмент JDK (комплект разработчика приложений на языке Java) javadoc использует документационные комментарии при подготовке автоматически созданной документации. |
Эта глава посвящена как пользоваться Javadoc. Мы посмотрим, как мы можем использовать Javadoc для создания полезной документации для кода Java.
Содержание
Что такое Javadoc?
Javadoc — это инструмент, который поставляется с JDK и используется для создания документации кода Java в формате HTML из исходного кода Java, для чего требуется документация в заранее определенном формате.
Ниже приводится простой пример, в котором строки внутри /*….*/ представляют собой многострочные комментарии Java. Точно так же строка, предшествующая //, является однострочным комментарием Java.
Пример 1
Вы можете включить необходимые HTML-теги внутри части описания. Например, в следующем примере используется
используется для создания разрыва абзаца.
Пример 2
Теги Javadoc
Инструмент javadoc распознает следующие теги:
| Тег | Описание | Синтаксис |
| @author | Добавляет автора класса. | @author name-text |
| Отображает текст шрифтом кода без интерпретации текста как разметки HTML или вложенных тегов javadoc. | ||
| Представляет относительный путь к корневому каталогу сгенерированного документа от любой сгенерированной страницы. | ||
| @deprecated | Добавляет комментарий, указывающий, что этот прикладной программный интерфейс больше не следует использовать. | @deprecated deprecatedtext |
| @exception | Добавляет подзаголовок Throws в сгенерированную документацию с именем класса и текстом описания | @exception class-name description |
| Наследует комментарий от ближайшего наследуемого класса или реализуемого интерфейса | Inherits a comment from the immediate surperclass. | |
| Вставляет встроенную ссылку с видимой текстовой меткой, которая указывает на документацию для указанного пакета, класса или имени члена указанного класса. | ||
| Идентично <@link>, за исключением того, что подпись ссылки отображается в виде обычного текста, а не шрифта кода. | ||
| @param | Добавляет параметр с указанным именем параметра, за которым следует указанное описание, в раздел «Параметры». | @param parameter-name description |
| @return | Добавляет раздел «Возврат» с текстом описания. | @return description |
| @see | Добавляет заголовок «Смотрите также» со ссылкой или текстовой записью, указывающей на ссылку. | @see reference |
| @serial | Используется в комментарии к документу для сериализуемого поля по умолчанию. | @serial field-description | include | exclude |
| @serialData | Документирует данные, записанные методами writeObject() или writeExternal(). | @serialData data-description |
| @serialField | Документирует компонент ObjectStreamField. | @serialField field-name field-type field-description |
| @since | Добавляет заголовок «От» с указанным текстом в созданную документацию. | @since release |
| @throws | Теги @throws и @exception являются синонимами. | @throws class-name description |
| Когда <@value>используется в комментарии к документу статического поля, он отображает значение этой константы. | ||
| @version | Добавляет подзаголовок «Версия» с указанным текстом версии в сгенерированные документы при использовании параметра -version. | @version version-text |
Пример
Следующая программа использует несколько важных тегов, доступных для комментариев к документации. Вы можете использовать другие теги в зависимости от ваших требований.
Источник
IT Novella
Javadoc — стандартный генератор документации в HTML-формате из комментариев исходного кода.
Для создания описания к элементу(поле, класс, метод) используются специальный комментарий, расположенный выше этого элемента:
Для документирования можно использовать дескрипторы, вот некоторые из них: @author — автор @version — версия @since — указывает с какой версии появился этот блок кода @see — ссылка на другое место в документации @param — передаваемый параметр методу @return — описание возвращаемого значения метода @exception и @throws — описание исключений @deprecated — документирование устаревших частей кода — создание ссылки, можно вставлять в любое место — описание значения переменной
Как видно, в документации можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и через символ «#» его метод или поле.
Вот пример использования ссылок для документирования перегруженного конструктора:
На выходе получаем:
Пример документации конструктора
Чтобы увидеть документацию в eclipse выделите элемент и нажмите F2.
Источник
Android Studio — советы и хитрости | Для разработчика андроид-приложений
Если вы никогда ранее не использовали Android Studio и не знакомы с интерфейсом IntelliJ IDEA , эта статья дает советы для повышения производительности, которые помогут вам начать работу с некоторыми из наиболее распространенных задач.
Функции производительности
Android Studio включает в себя ряд функций, которые помогут вам быть более продуктивным в вашем коде. В этом разделе коснемся некоторых ключевых функций, которые помогут вам работать быстро и эффективно.
Smart Rendering
Используя умный рендеринг, Android отображает ссылки для быстрого исправления ошибок рендеринга. Например, если вы добавите кнопку для макета без указания атрибутов ширины и высоты, Android Studio отображает сообщение рендеринга с предложением автоматически добавлять все недостающие атрибуты. Щелчок по сообщению добавляет недостающие атрибуты к макету.
Визуализация растрового изображения в отладчике
Во время отладки, теперь вы можете щелкнуть правой кнопкой мыши на растровых переменных в вашем приложении и вызвать View Bitmap. Это позволит получить связанные данные из отлаживаемого процесса и отобразит растровое изображение в отладчике.
Рисунок 1. Визуализация растрового изображения в отладчике Android Studio
Фильтры в окне вывода сообщений
При проверке результатов сборки приложения, вы можете фильтровать сообщения по типу, чтобы быстро найти нужные.
Рисунок 2. Фильтры в окне вывода сообщений
Установка иерархии Activity
При создании новой Activity в визарде можно выбрать для нее родительскую Activity. Установка иерархии автоматически определяет кнопку Вверх, которая появляется при просмотре в Панели действий (Action Bar) дочерней Activity, что избавляет от необходимости вручную прописывать кнопку Вверх в файле menu.xml.
Создание макетов
Android Studio предлагает расширенный редактор макетов, который позволяет добавлять виджеты в макет простым перетаскиванием и обеспечивает предпросмотр макетов при редактировании XML.
При редактировании в текстовом представлении можно предварительно просмотреть макет на устройствах, открыв область Preview, доступную в правой части окна редактора. В области Preview Вы можете изменить предварительный просмотр, выбирая различные варианты наверху области просмотра, например, модель андроид-устройства, тему оформления, версию платформы и т.д. Чтобы предварительно просмотреть отображение макета на многих устройствах одновременно, выберите Preview All Screen Sizes из выпадающего списка.
Рисунок 3. Предварительный просмотр всех экранов
Вы можете переключиться в графическое представление макета в редакторе, нажав Дизайн в нижней части окна. При редактировании в режиме проектирования, вы можете показать и скрыть доступные для перетаскивания виджеты путем нажатия палитру на левой стороне окна. При выборе Design на правой стороне окна выводится панель с иерархией макета и список свойств для каждого View в макете.
Работа с IntelliJ IDEA
Приводим список некоторых приемов редактирования кода, которые вы можете использовать при создании приложений в Android Studio.
Для получения полной пользовательской документации для интерфейса IDEA IntelliJ (на котором базируется Android Studio), обратитесь к документации IntelliJ IDEA .
Alt + Enter комбинация клавиш
Используйте комбинацию клавиш Alt + Enter для быстрого исправления ошибок, таких как пропущенный импорт или значение переменной, отсутствующие ссылки и т.д. IntelliJ IDE по возможности исправит ошибки, или предложит наиболее подходящее решение.
Ctrl + D комбинация клавиш
Комбинация Ctrl + D позволяет быстро дублировать строку или фрагмент кода. Просто выделите нужный вам код и нажмите Ctrl + D.
Меню навигации
В случае, если вы не знакомы с API класса, меню Navigate позволяет перейти непосредственно к методу класса или имени поля, без необходимости поиска отдельных классов.
Идентификация областей кода
Можно выделять цветом участки кода, чтобы было легче ориентироваться в нем. Например, вы можете выделить весь код, связанный с определенной строкой меню.
Внешние аннотации
Создавайте аннотации в коде или во внешнем файле аннотаций. Android Studio IDE сохраняет ссылки и проверяет соответствие, например, установку типа данных строки как NOT NULL.
Использование XML и SQL
Android Studio IDE позволяет работать с разными языками, встроенными в исходный код, в частности с XML и SQL. Поддерживается синтаксис, подсветка ошибок и подсказки по коду встроенного языка, проверка значений регулярных выражений и проверка XML и SQL операторов.
Сворачивание кода
Позволяет выборочно скрывать и отображать разделы кода для удобства чтения. Например, выражения ресурсов или код для вложенного класса можно сложить или скрыть в одной строке, чтобы сделать структуру внешнего класса более удобочитаемой. Внутренний класс может быть позже развернут при обновлении.
Предварительный просмотр изображений и цвета
При ссылке в коде на изображения и иконки появляется значок (в натуральную величину на разных плотностях) на полях кода, предоставляющий возможность предварительного просмотра, чтобы помочь вам проверить эталонное изображение или значок. Нажатие F1 в предварительном просмотре изображения или значка отображает подробную информацию ресурсов, например DP параметр.
Быстрая документация F1
Вы можете теперь осмотреть атрибуты темы, используя View > Quick Documentation (F1), видеть иерархию наследования темы и значения решения для различных атрибутов.
Если Вы вызываете View> Quick Documentation (обычно связываемый с F1) на атрибуте темы android:textAppearanceLarge, Вы будете видеть иерархию наследования темы и разрешенные значения для различных атрибутов, которые втянуты.
Источник
