Коментари и вградена документация

Коментари и вградена документация

/* Това е

Забележете че всичко между /* и */ се игнорира така че е същото да кажем:

/* Това е коментар който
про­дължава на повече от една линия */

Втората форма на коментара идва от C++. Това е коментар на един ред, който започва с // и продължава до края на реда. Този тип коментар е удобен и много използван, понеже е лесен. Няма нужда да ловувате по клавиатурата за да намерите / и после * (просто натискате един клавиш два пъти) и няма нужда да затваряте коментара. Така че често ще видите:

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

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

Инструментът за извличане на коментарите е наречен javadoc. Той използва част от технологията на Java компилатора за да гледа за специалните белези, кои­то вие пишете в кода си. Не само се извличат коментарите, маркирани по то­зи начин, но също се дава и името на класа или метода, свързан с коментара. По този начин може да се разминете с минимален труд при създаването на при­лич­на документация.

Изходът от javadoc е HTML файл който може да видите със своя броузър. Този ин­струмент ви позволява да поддържате единствен сорс файл и да извличате от не­го полезна документация. Поради javadoc ние разполагаме със стандарт за съз­даване на документация и е достатъчно лесно да очакваме и даже да по­ръ­ча­ме документация за всичките Java библиотеки.

Синтаксис

Има три “типа” коментарна документация, които съответстват на елемента, който предхождат: клас, променлива или метод. Тоест, коментар на клас за­поч­ва преди клас; коментар на променлива започва точно при дефиниране на про­мен­лива и коментар на метод започва точно при започването на дефиниция на ме­тод. Като прост пример:

/** Коментар на клас */
public class docTest {

/** Коментар на променлива */

public int i;

/** Коментар на метод */

public void f() {}

}

Забележете че javadoc ще обработи коментарите само за public и protected чле­но­вете. Коментарите за private и “приятелски” (виж глава 5) се игнорират и ня­ма да видите изход за тях. (Може да използвате -private флаг за да включите и private членовете.) Това има смисъл защото public и protected членовете са до­стъп­ни извън файла, което е перспективата на клиент-програмиста. Обаче всич­ки class коментари се включват в изхода.

Вграден HTML

Javadoc дава HTML команди чрез произведения HTML документ. Това позволява пълно използване на HTML; обаче основният мотив е да може да се форматира кода, както в:

/**
*

* System.out.println(new Date());
*

*/

Може също да използвате HTML точно както бихте го правили в обикновени Web документи:

/**
* You can even insert a list:
*

*
1. Текст едно
   *
2. Текст 2
   *
3. И три
   *

*/

Запомнете че в документен коментар звездите в началото на линията се из­хвър­лят от javadoc, както и водещите празни позиции (шпации - б.пр). Javadoc пре­фор­матира всичко така че да съответства на стандартния формат на доку­мен­та­ция­та. Не използвайте заглавия като

или

---

за вграден HTML понеже javadoc слага свои и вашите ще си пречат с тях.

Всички типове от коментарна документация – клас, променлива и метод – под­дър­жат вграден HTML.

@see: отнасяне към други класове

Всичките три типа документни коментари могат да съдържат @see директиви, които позволяват да се отнасяте към други класове. Javadoc ще произведе HTML със @see хиперсвързани към другата документация. Формите са:

@see classname

@see fully-qualified-classname

@see fully-qualified-classname#method-name

Всяка добавя хиперсвързан “See Also” вход в генерираната документация. Java­doc няма да провери за валидност хипервръзките, които сте посочили.

Директива за документиране на клас

Заедно с вградения HTML и @see отнасянията документацията на клас може да включ­ва и информация за версията и авторското име. Документацията за клас мо­же също да се използва с интерфейси (описано е по-нататък в книгата).

@version

Има следната форма:

@version version-information

където version-information е каквато искате да включите информация. Когато -ver­sion флаг се сложи на javadoc командния ред, информацията за версията ще се извика специално за HTML документацията.

@author

Има следната форма:

@author author-information

където author-information е, предполага се, вашето име, но може да включва елек­тронен адрес и друга подходяща информация. Когато -author флагът при­със­тва в командната линия, информацията за автора се извиква специално в HTML документацията.

Може да имате няколко директиви за автор при списък от автори, но те трябва да са последователно разположени. Всичката авторска информация ще бъде съ­бра­на заедно в генерираната HTML документация.

Директиви за документиране на променлива

Може да включва само вграден HTML и @see отгнасяния.

Директиви за документация на метод

Както и вградена документация и @see отнасяния, методите допускат дирек­ти­ви за параметри, връщани стойности и изключения.

@param

Формата е:

@param parameter-name description

където parameter-name е идентификатор в списъка на параметрите, description е текст който може да заеме няколко линии. Описанието се счита завършено, ко­гато се срещне нова директива за документцията. Може да имате всясасъв брой, предполагаемо по едно за всеки параметър.

@return

Има следната форма:

@return description

където description дава смисъла на връщаната стойност. Може да продължи на след­ващи линии.

@exception

Изключенията ще се опишат в глава 9, но накъсо те са обекти, които могат да бъдат “изхвърлени” от метод, който се е провалил. Въпреки че само едно изключение може да възникне като извикате метод, конкретен обект би могъл да произведе неограничен брой типове изключения, всяко от които трябва да се опише. Така че формата на директивата е:

@exception fully-qualified-class-name description

където fully-qualified-class-name дава недвусмислено име на клас, който е опи­сан някъде, а description (може да заеме няколко линии) казва защо този кон­кре­тен случай на изключение може да възникне при викането на метода.

@deprecated

Това е ново в Java 1.1. То е за да се бележат черти, които са били заместени от по­-но­ви такива. Белегът съветва да не се използва повече старата черта, понеже в бъдеще тя вероятно ще бъде махната. Методите които са маркирани с @deprecated карат компилатора да издаде предупреждение, ако се използват.

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

Ето пак първата Java програма, този път с добавени коментари за докумен­та­ция:

//: c02:Property.java

import java.util.*;
/** The first Thinking in Java example program.

* Lists system information on current machine.

* @author Bruce Eckel

* @author http://www.BruceEckel.com

* @version 1.0

*/

public class Property {

/** Sole entry point to class & application

* @param args array of string arguments

* @return No return value

* @exception exceptions No exceptions thrown

*/

public static void main(String[] args) {

System.out.println(new Date());

Properties p = System.getProperties();

p.list(System.out);

System.out.println("--- Memory Usage:");

Runtime rt = Runtime.getRuntime();

System.out.println("Total Memory = "

+ rt.totalMemory()

+ " Free Memory = "

+ rt.freeMemory());

}

} ///:~

Първия ред:

//: Property.java

използва моя собствена техника за слагане на ‘:’като специален маркер за ко­мен­тара, съдържащ името на файла. Последния ред също свършва с коментар, кой­то показва края на вистинга на сорсовия код, което позволява да бъде авто­ма­тично извлечено от текста на книгата и да бъде дадено на компилатора. Това е описано детайлно в глава 17.

Каталог: Java
Java -> Лекция Изключения. Уравнение на КортевегДеВриз
Java -> Създаване на прозорци и аплети
Java -> Лекция 2 Типове данни. Класове и обекти. Числено интегриране
Java -> Национална академия по разработка на софтуер
Java -> Java за цифрово подписване на документи в уеб
Java -> Запознаване с JavaScript. Запознаване с Java Script
Java -> Програма за изчисляване на средна стойност

Изтегляне 13.53 Mb.

Сподели с приятели: