Чтобы понять различные компоненты Javadoc, сначала нужно понять основы Java. Знакомство с названиями различных компонентов Java позволит вступать в разговоры и понимать код на высоком уровне. При описании различных аспектов примера кода, знание того, когда вызывать что-либо, класс, метод, параметр или перечисление, может иметь решающее значение для доверия к создаваемой документации.
В этом разделе будет краткий ускоренный курс по основам. Не стоит волноваться, если что-то будет непонятным. Для получения более подробной информации о языке Java, можно обратиться например к lynda.com или safaribooksonline. Сейчас же остановимся на некоторых основных понятиях в Java, которые будут важны для понимания тегов и элементов Javadoc.
Сравнение API нативной библиотеки и REST
Гибкость и широкое использование Java делают его одним из лучших языков программирования для технических писателей. Java не привязан к конкретной языковой платформе. Вместо этого Java-код компилируется в байтовый код. Платформа, на которой разворачивается код, содержит виртуальную машину Java (JVM), которая интерпретирует байт-код. Следовательно, с помощью JVM разные платформы могут интерпретировать и выполнять код Java, что дает Java большую гибкость на разных платформах.
Классы - это шаблоны или чертежи, которые управляют практически всем в Java. Проще понять классы на примере. Можно представить класс как чертеж велосипеда. Существует много различных типов велосипедов (велосипеды Trek, специализированные велосипеды, гигантские велосипеды, велосипеды Raleigh и т.д.). Но это всего лишь разные экземпляры общего класса "велосипед".
Код Java начинается с определения классов. Каждый класс является своим собственным файлом и начинается с заглавной буквы. Имя файла соответствует имени класса, что означает, что есть только один класс на файл.
Каждый класс может содержать несколько полей (переменные для класса) и методов (подпрограммы, которые может выполнять класс).
Перед именем класса прописывается модификатор доступа, который указывает, как получить доступ к классу. Вот несколько вариантов модификаторов доступа:
- public: публичный класс;
- private: доступ только пакетам;
- static: запрещены изменения класса;
- abstract: может быть создан только подкласс.
Пример класса:
public class Bicycle{
//code...
}
В основном стоит сосредоточиться на public классах , так как эти классы будут использоваться внешними разработчиками. public классы являются API библиотек.
Методы - это подпрограммы или функции, которые может выполнять класс. Например, на велосипеде можно крутить педали, тормозить и поворачивать. Класс может иметь столько методов, сколько ему нужно.
Методы могут принимать аргументы, поэтому после имени метода ставят круглые скобки (). Аргументы - это переменные, которые используются в коде для этого метода.
Например:
add(a, b) {
sum = a + b;
}
Методы могут возвращать значения. Когда метод завершается, значение может быть возвращено вызывающей стороне метода.
Перед своим именем метод указывает, какой тип данных он возвращает. Если метод ничего не возвращает, в списке указывается void. Другие варианты: string или int.
Пример нескольких методов для класса Bicycle:
class Bicycle {
void turn() {
// code ...
}
void pedal(int rotations) {
System.out.println("Your speed is " + rotations + " per minute".);
}
int brake(int force, int weight) {
torque == force * weight;
return torque;
}
}
В примере видно, как метод brake принимает два аргумента - force и weight. Эти аргументы являются целыми числами, поэтому Java ожидает здесь целые числа. (Необходимо указать тип данных перед параметрами в методе.) Аргументы, передаваемые в этот метод, используются для вычисления крутящего момента torque. Затем torque возвращается вызывающей стороне.
У Java есть разные типы методов. Методы экземпляра Instance могут использоваться только из объектов, созданных из класса. Статические методы Static можно использовать непосредственно из класса, не создавая экземпляр объекта в первую очередь. Абстрактные Abstract методы могут использоваться только через подклассы.
Где-то в Java-приложении будет метод main, который выглядит следующим образом:
public static void main(String[] args) {
}
Внутри метода main добавляется код для запуска своей программы. В результате код внутри метода main ссылается на другие объекты (которые создаются из классов). Виртуальная машина Java будет искать основной метод для запуска кода приложения.
Поля - это переменные, доступные в классе. Переменная - это плэйсхолдер, который заполняется значением в зависимости от того, что хочет пользователь.
В полях указывают типы данных, потому что все данные в Java «статически типизированы» (имеется в виду, что их формат / длина определены), так что данные не занимают больше места, чем нужно. Некоторые типы данных включают в себя byte, short, long, int, float или double. Это числа или десятичные знаки разных размеров. Можно указывать char, string или boolean.
Пример нескольких полей:
class Bicycle {
String brand;
int size;
}
Часто поля «инкапсулируются» методами getter и setter, что означает, что их значения устанавливаются защищенным способом. Пользователи вызывают один метод, чтобы установить значение поля, и другой метод, чтобы получить значение поля. Таким образом можно избегать установку пользователями неправильных значений или неправильных типов данных для полей.
Поля, которые являются постоянными во всем проекте Java, называются ENUMS. В качестве альтернативы, поля имеют модификаторы public static final.
Объекты являются экземплярами классов. Это Treks, Raleighs, Specialized и т.д. класса Bicycle.
Для использования класса Bicycle, создается экземпляр этого класса. Экземпляр класса называется объектом. Вот как выглядит создание экземпляра класса:
Bicycle myBicycle = new Bicycle();
Пишется имя класса, за которым следует имя объекта для класса. Затем присваивается объекту новый экземпляр класса. Теперь есть myBicycle для работы.
Объект наследует все поля и методы, доступные классу.
К полям и методам объекта можно получить доступ, используя точечную нотацию, например:
myBicycle Bicycle = new Bicycle();
myBicycle.brand = "Trek";
myBicycle.pedal();
В нативной библиотеке вряд ли будет много объектов. Вместо этого разработчики, которые реализуют API, будут создавать объекты. Однако, в эталонной реализации или примере кода реализации API, объектов будет множество.
Конструкторы - это методы, используемые для создания новых экземпляров (объектов) класса. Конструктор по умолчанию для класса выглядит так же, как и выше, с новым Bicycle ().
Конструктор использует то же имя, что и класс, и сопровождается круглыми скобками (потому что конструкторы являются методами).
Часто классы имеют конструкторы, которые инициализируют объект с определенными значениями, переданными в конструктор.
Например, предположим, был конструктор, который инициализировал объект с брендом и размером:
public class Bicycle{
public Bicycle(String brand, int size) {
this.brand = model;
this.size = size;
}
}
Теперь можно использовать этот конструктор при создании нового объекта Bicycle:
Bicycle myBicycle = new Bicycle ("Trek", 22);
Лучшей практикой является включение конструктора, даже если он используется по умолчанию.
Классы организованы в различные пакеты в проектах Java. Пакеты похожи на папки или каталоги, в которых хранятся классы. Размещение классов в пакетах помогает избежать конфликтов имен.
Пакеты перечисляются в верхней части файла при создании класса, если этот класс находится в пакете с названием транспортных средств:
package vehicles
public class Bicycle {
//
}
Классы также устанавливают границы доступа в зависимости от пакета. Если модификатор доступа не говорит public, класс будет доступен только для членов одного и того же пакета. Если модификатор доступа protected, класс доступен только для класса, пакета и подклассов.
При создании экземпляра класса (в случае, если файл находится за пределами пакета), необходимо импортировать пакет в класс, например так:
import vehicles
public static void main(String[] args) {
}
Если пакеты содержатся внутри других пакетов, для доступа к внутренним пакетам прописывается полный путь, например:
import transportation.motorless.vehicles
Здесь видим пакет transportation, содержащий пакет motorless, содержащий пакет vehicles. Соглашения об именах пакетов аналогичны URL-адресам в обратном направлении (com> yoursite> subdomain).
Maven поддерживает управление пакетами для проектов Java. Maven автоматически получит все зависимости пакетов для проекта при установке проекта Maven.
Чтобы избежать неработающего кода, разработчики помечают потенциальные проблемы посредством обработки исключений. Исключения говорят: "если здесь есть проблема, пометьте ошибку этим исключением, а затем продолжите выполнение кода".
Различные типы ошибок вызывают разные исключения. Определив тип создаваемого исключения, проще устранять проблемы, возникающие при разрыве кода, поскольку происходящая конкретная ошибка известна.
Определять конкретное исключение, которое выбрасывает класс в имени класса можно после ключевого слова throws:
public class Bicycle throws IOException {
}
При указании исключения, перечисляется тип исключения, используя определенный тег Javadoc.
Некоторые классы могут расширять другие классы. Расширение класса означает, что класс наследует свойства другого класса. Когда один класс расширяет другой, можно увидеть следующую запись:
public class Bicycle extends Vehicle {
}
Этот код означает, что Bicycle наследует все свойства Vehicle и затем может дополнять их.
Интерфейс - это класс, в котором есть методы без кода внутри метода. Интерфейсы предназначены для реализации другим классом, который будет вставлять свои собственные значения для методов. Интерфейсы - это способ формализации класса, который будет иметь много подклассов. Интерфейсы вынуждают подклассы стандартизировать общие строки и методы.
Расширение файла для класса обозначается .java, но при компиляции Java Development Kit в программу Java файл становится .class. Файл .class представляет собой двоичный код, что означает, что только компьютеры (в данном случае виртуальная машина Java или JVM) могут читать его.
Разработчики часто упаковывают java-файлы в JAR-архив, который похож на zip-файл. При передаче файла Java, используется файл JAR, для удобства вставки в проекты Java.
Разработчики добавляют JAR-файл в пути к классам, чтобы сделать классы доступными для проекта. Для этого они щелкают правой кнопкой мыши на свой проект и выбирают Properties. В диалоговом окне они выбирают Java Build Path и затем нажимают вкладку Libraries. Затем они нажимают Add JARs и выбирают нужный JAR-файл.
При получении файла JAR разработчики могут использовать классы и методы, доступные в JAR. Однако JAR не будет показывать им исходный код, то есть необработанные файлы Java. Для этого пользователи будут консультироваться с Javadoc.
При распространении адресной реализации, которая состоит из набора исходных файлов Java (чтобы разработчики могли видеть, как интегрировать продукт в Java), проще передавать zip-файл, содержащий весь проект.
Файл WAR представляет архив веб-приложения. WAR - это скомпилированное приложение, которое разработчики развертывают на сервере для запуска приложения. Соответственно, JAR - интегрируется в проект Java, в то время как разработчики активно создают приложение, WAR - это развернутая программа, которую запускается с сервера.
Этого, вероятно, достаточно для понимания различных компонентов Javadoc.
Вот краткое изложение понятий, о которых мы говорили:
- класс: чертеж чего-любо;
- объект: экземпляр класса;
- метод: функция класса или объекта;
- поля: переменный класса или объекта;
- конструктор: метод создания объекта класса;
- пакет: папка, группирующая классы;
- модификатор доступа (например
public): область, в которой вещь может быть доступна; - интерфейс: скелет класса с пустыми методами (используется для стандартизации);
- Enum: тип данных, предлагающий предопределенные константы;
- подкласс: класс, наследующий поля и методы другого класса;
- JAR-файл: архив java классов, аналогичный zip-файлам;
- WAR-файл: скомпилированное java приложение, готовое для развертывания на сервере.
Теперь можно разумно использовать эти термины в документации и, по крайней мере, иметь представление о том, что происходит.
Теперь, имея представление о конкретном языке программирования и элементах в Java, можно понять, насколько API-интерфейсы нативных библиотек отличаются от API-интерфейсов REST. Для документирования нативных API библиотек, необходимо ознакомиться с языком программирования. API REST, напротив, не зависят от языка, поэтому они, как правило, более доступны.