Ajouter un commentaire, une note, faire une correction, référencer un lien, ...

JavaDoc

Documentation directe dans le code source

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]





Version imprimable...
Envoyer à un ami...

JavaDoc

Articles [3] - Outils [12] -

Sujets liés

Outils pour fichiers sources
Ant
Maven
tous les sujets...
Java - XML - Web

Sites de référence


Hiérarchie

Java
JSP
EJB
Java / XML
J2EE
J2ME
Embedded Java
Jini
Java Projects
Projet JXta
Brazil
Sun ONE
Java Media API
Java API
Applications Java
Java Security
Java Web Start
Applet / Pug-in
JavaDoc
tous les sujets...
Choisir les meilleures vitamines...



Films Disney

Vidéos sur les OGM

Villes de France sur GoogleMap

Index des sujetsJava

Java - XML - Web


Informatique


Voir Aussi



Google