2.1 Комментарии
Язык Java поддерживает три типа комментариев,
Однострочные
Многострочные
Документационный
2.1.1 Однострочные комментарии
Однострочный комментарий начинается символами // и завершается в конце строки. Компилятор игнорирует всё от // до конца строки.
Пример 1:
// This example demonstrates the use of single line comments
public class HelloWorld //Declare class as
{ // with name HelloWorld
public static void main(String args []) // Define main
{
System.out.println( Hello World. ); // Prints Hello
// World to console
} // End of main
} // End HelloWorld class
2.1.2 Многострочные комментарии
Многострочный комментарий начинается с /* и заканчивается */.
Он может занимать одну или более строк.
Компилятор игнорирует всё от /* до */.
Пример 2:
// This example demonstrates the use of multi line comments
/* This is a sample class which is used to demonstrate the use of multi-line comments. This comment does not appear in the java documentation */
public class Example
{
public static void main(String[] args)
{
System.out.println( Welcome to my World !!! );
}
}
2.1.3 Документационные комментарии
Документационные комментарии начинаются с / ** и заканчиваются / и могут также занимать одну или более строк. Компилятор игнорирует этот вид комментария, точно так же как игнорируются комментарии / и */.
Документационные комментарии идут дальше, позволяя создание отдельной документации через использование javadoc инструмента, javadoc - это инструмент, позволяющий пользователю создавать документацию API в форме страниц HTML. Документационная информация собирается непосредственно от исходного текста и комментариев документа.
Мы можем также внедрять html-тэги в пределах комментариев документа. Однако, если мы должны включить <,> или & в описании, то мы должны использовать <, > и & соответственно.
Инструмент javadoc распознаёт только документационные комментарии, располагающиеся сразу перед классом, интерфейсом, конструктором, методом или полевыми объявлениями. Также при объявлении, мы можем иметь только один комментарий.
Как было сказано ранее, документационные комментарии начинаются с / ** и заканчиваются */. Каждая строка в пределах комментария должна начаться с *. В тоже время мы можем не учесть продвижение *, рискуя пропустить любой сдвиг, который мы, возможно, поместили в пределах комментария. Следовательно, желательно, чтобы мы начинали каждую строку со звездочки, *.
Первое предложение должно отображать краткое описание объекта, то есть класса, интерфейса, конструктора, метода или поля. Это должно выглядеть кратко и информативно.
Теперь давайте добавим документационные комментарии к нашему приложению HelloWorld:
Пример 3:
/**
*
HelloWorld.java
*
This class is the classic HelloWorld application.
*
*
*
*/
class HelloWorld
{
public static void main (String args[])
{
System.out.println ( Hello World! );
}
} // end HelloWorld
Комментарий в строках 1-9 - комментарий Javadoc, которые являются документационными. Обратите внимание на выравнивание звездочек в многострочных комментариях: это - соглашения, принятые в Java. Конец комментарий HelloWorld здесь не так необходим, но в длинном классе это может быть полезно в сообщениях о методе или операторных блоках.
