JavaDoc

Documentation directe dans le code source

Table des matières :

Qu'est ce que JavaDoc ?
Overview (site de Sun)
Quoi de neuf avec Javadoc ? / What's New in Javadoc ?
Terminology
Référencer une méthode, un constructeur, une classe, ...
Exemple d'utilisation de JavaDoc avec ANT

Qu'est ce que JavaDoc ?

Javadoc est un outil qui vient en standard avec le JDK/SDK de Sun. Il permet au développeur Java de générer une documentation complète du code se basant sur les commentaires dans le code source Java (commentaires de classe, interfaces, méthodes, attributs et packages).
Javadoc, lors de sa sortie avec la première version de Java en 1995, était une autre innovation de Sun. Depuis, d'autres langages proposent le même style d'outils.
Les fichiers générés sont au format HTML, mais on peut trouver d'autres 'doclet' pour générer d'autres types de fichiers, par exemple XML, PDF, ...

Bon à savoir : On peut aussi documenter un package, pour cela créer simplement un fichier package.html dans les packages à documenter. Toute la partie entre <body> et </body> sera utilisée lors de la génération Javadoc.

Source : Loribel

Overview (site de Sun)

Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, inner classes, interfaces, constructors, methods, and fields.
You can use Javadoc doclets to customize Javadoc output. A doclet is a program written with the doclet API that specifies the content and format of the output to be generated by the javadoc tool. You can write a doclet to generate any kind of text-file output, such as HTML, SGML, XML, RTF, and MIF.

Source : Site de Sun

Quoi de neuf avec Javadoc ? / What's New in Javadoc ?

Historique des versions de Javadoc. Les versions de Java et de Javadoc sont liées.

New Features 1.4.2

Can now inherit comments from source files not being documented

New Features 1.4.1

Added package and class names as keywords in <META> tags.

New Features 1.4.0

New Tags :{@linkplain}, {@inheritDoc}, @serial, {@value}
New Options : -breakiterator, -docfilessubdirs -exclude, -excludedocfilessubdir -nocomment, -noqualifier, -quiet, -source, -linksource, -subpackages, -tag, -taglet

New Features 1.3.0

New Tags : {@docRoot}
MIF doclet : This adds the ability to generate MIF output, for importing into FrameMaker and eventual conversion to PDF, PS, RTF, Word, or WordPerfect. (download it)

New Features 1.2.0

Changes for Writing Doc Comments

The following list summarizes in one place all features listed elsewhere that can have an impact on how you would write doc comments.
The first sentence of each class description should be a summary statement.
Package-level comments are now possible.
The first sentence of each package description should be a summary statement.
System-wide (overview) comments are now possible.
New Javadoc tags are available for use in doc comments.
Copies new "doc-files" directory for holding images and examples.
Hierarchical destination file structure
Possible incompatibilities between 1.1 and 1.2 doc comments

Doclet API : Javadoc now has a Doclet API to which you can write doclets.
New Tags : @throws, @see (now accepts packages, HTML anchors and quoted strings), { @link apiname label}.
Provides more API information and links

Includes mechanisms for package-level and document-level information.
Incorporates one-line summaries for classes and packages like there have been for members.
Includes inherited API on class and interface pages.
Includes return types in method summaries, and field data types in field summaries.
Includes links to interfaces from members that implement that interface.
Includes list of subclasses for each class, and implementing classes for each interface.
Copies member descriptions from interfaces to implementing classes.
Includes a class hierarchy (tree) view for each package.
Introduces -link option for linking to external Javadoc-generated documents.
Includes list of deprecated API.
Omits the keywords native and synchronization (which are not part of the Java spec).
Copies new "doc-files" directory for holding images and examples.

Customizable title, header and footer

Source : Javadoc 1.4.2 Tool

Terminology

API documentation (API docs) or API specifications (API specs) : On-line or hardcopy descriptions of the API, intended primarily for programmers writing in Java. These can be generated using the Javadoc tool or created some other way. An API specification is a particular kind of API document, as described above. An example of an API specification is the on-line Java 2 Platform, Standard Edition API Specifications. An example of an API document is the Java Class Libraries book by Chan/Lee.
Documentation comments (doc comments) : The special comments in the Java source code that are delimited by the /** ... */ delimiters. These comments are processed by the Javadoc tool to generate the API docs.
javadoc : The JDK tool that generates API documentation from documentation comments.

Référencer une méthode, un constructeur, une classe, ...

Que ce soit avec le tag @see ou @link voici les possibilités:

@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id...)
@see #method(Type, Type,...)
@see #method(Type id, Type, id...)
@see Class
@see Class#field
@see Class#Constructor(Type, Type...)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type id, Type, id)
@see package

Pour le tag @link, on utilisera la syntaxe { @link XXX label}. XXX étant la même chose que ce que l'on peut trouver après @see.
Remarque : Dans les fichiers package.html, il faut utiliser une référence des classes avec le nom du package, par exemple { @link gb.fwk.util.MyClass MyClass} et non { @link MyClass MyClass} même s'il s'agit de la documentation du package gb.fwk.util.

Exemple d'utilisation de JavaDoc avec ANT

<property name="src" value="./src" />
<property name="dirApi" value="./target/docs/apidocs" />
<property name="title" value="Title for API" />


<target name="javadoc">
  <javadoc
    packagenames="*"
    sourcepath="${src}"
    destdir="${dirApi}"
    author="true"
    version="true"
    use="true"
    windowtitle="${title}"
    splitindex="true">
    <!-- defaultexcludes="yes" -->
  <doctitle><![CDATA[<h1>${title}</h1>]]></doctitle>
  <!-- <header>${title}</header> -->
  <bottom>
     <![CDATA[<i>Copyright © 2003 -
     <a href="mailto:xxx">Loribel</a> - All Rights Reserved.</i>]]>
  </bottom>


  <group title="Utililities" packages="gb.fwk:gb.fwk.util*"/>
  <group title="Business Object" packages="gb.fwk.busines*"/>
  <group title="Graphic User Interface" packages="gb.fwk.gui*"/>
  <group title="XML Tools" packages="gb.fwk.xml*:gb.fwk.file.xml"/>


  <tag name="todo" scope="all" description="To do:" />
  <tag name="myTag" scope="all" description="My Tag:" />
  <link offline="true"
     href="http://java.sun.com/products/jdk/1.4.1/docs/api/" />
  <!-- <link href="http:.../docs/api/"/> -->
  </javadoc>
</target>

JavaDoc Home page
JavaDoc 1.4.2 Tool
How to Write Doc Comments for the Javadoc Tool [SUN]

Articles [3] - Outils [12] -