1_1_8 Javadoc1_1_8 Javadoc

Apoyo SSD3Apoyo SSD3

Mtl Lourdes CahuichMtl Lourdes Cahuich 22

Javadoc comments are written by the Javadoc comments are written by the programmer, and then processed by the programmer, and then processed by the program Javadoc. program Javadoc.

The program parses the Javadoc The program parses the Javadoc comments and the overall structure of the comments and the overall structure of the program, producing a set of HTML pages program, producing a set of HTML pages that serve as documentation for the that serve as documentation for the programprogram

Mtl Lourdes CahuichMtl Lourdes Cahuich 33

Advice on DocumentingAdvice on Documenting

It costs significantly more to maintain It costs significantly more to maintain software than it does to develop it. software than it does to develop it.

The task of maintenance is far easier if the The task of maintenance is far easier if the software is well documented. software is well documented.

Many programmers will document a Many programmers will document a program program afterafter it is finished. This is a it is finished. This is a mistakemistake

Mtl Lourdes CahuichMtl Lourdes Cahuich 44

Documenting should be done in Documenting should be done in conjunction with coding.conjunction with coding.

Procrastinating results in a daunting Procrastinating results in a daunting documentation task at the end, and the documentation task at the end, and the consequence is usually inferior consequence is usually inferior documentation.documentation.

Mtl Lourdes CahuichMtl Lourdes Cahuich 55

Using Javadoc enhances documentation. Using Javadoc enhances documentation. The documentation for the entire Java API The documentation for the entire Java API

is in Javadoc format.is in Javadoc format. Using Javadoc also greatly reduces the Using Javadoc also greatly reduces the

need for conventional source code need for conventional source code comments.comments.

Mtl Lourdes CahuichMtl Lourdes Cahuich 66

Javadoc SyntaxJavadoc Syntax

/** /**

* body text * body text

* body text * body text

* body text* body text

*/*/

Mtl Lourdes CahuichMtl Lourdes Cahuich 77

Most Javadoc comments include Most Javadoc comments include Javadoc Javadoc tagstags. .

Javadoc tags begin with the "at-symbol" Javadoc tags begin with the "at-symbol" ( @ ), followed by the name of the tag. ( @ ), followed by the name of the tag.

Each tag describes a particular attribute of Each tag describes a particular attribute of the entity being commentedthe entity being commented

Mtl Lourdes CahuichMtl Lourdes Cahuich 88

1.1. @author – programmer's name; used for @author – programmer's name; used for classesclasses

2.2. @version – version of the program; used for @version – version of the program; used for classesclasses

3.3. @param – description of a formal parameter; @param – description of a formal parameter; used for methods and constructorsused for methods and constructors

4.4. @return – description of a return value; used @return – description of a return value; used for methodsfor methods

5.5. @exception (or @throws) – description of an @exception (or @throws) – description of an exception; used for methods and constructorsexception; used for methods and constructors

6.6. @see – reference to a related entity; used for @see – reference to a related entity; used for classes, constructors, methods, and data fieldsclasses, constructors, methods, and data fields

Mtl Lourdes CahuichMtl Lourdes Cahuich 99

Once the Javadoc comments are Once the Javadoc comments are complete, use the complete, use the javadocjavadoc command to command to generate the program documentation.generate the program documentation.

The following figure illustrates the syntax The following figure illustrates the syntax for the for the javadocjavadoc command command

Mtl Lourdes CahuichMtl Lourdes Cahuich 1010

This will produce a collection of HTML pages.This will produce a collection of HTML pages. The collection can be viewed with a web The collection can be viewed with a web

browserbrowser This course will This course will onlyonly require Javadoc comments require Javadoc comments

for public and protected entities—classes, for public and protected entities—classes, constructors, methods, and variables that are constructors, methods, and variables that are preceded by the keyword public or protectedpreceded by the keyword public or protected