JavaDoc

Documentation du code avec JavaDoc

Ce site ne sera plus alimenté de contenu après août 2014. Tous les nouveaux articles seront redigés pour www.waitingforcode.com

Une bonne documentation du code est un élément crucial qui permet de pérenniser chaque projet. Depuis peu cet aspect est mis en avance dans le développement des applications PHP (grâce aux outils comme PHPDoc). Depuis longtemps il fait partie de chaque code écrit en Java. Tout cela grâce à un outil nommé Javadoc.

Regardons d'abord de différents types de commentaires en Java sur l'exemple d'un code banal qui affiche une chaîne de caractères sur l'écran :

public class Comments {
    /*
      This is multiple line comments.
      You can put the text everywhere you want.
     */
    public static void main(String[] args) {
        // this is line comment
        System.out.println("Test");
    }
}

Comme dans d'autres langages, il y a un commentaire sur plusieurs lignes (compris entre /* et */) et sur une seule ligne (précédé par //). Jusque là rien de compliqué. Regardons maintenant comment transformer ceci en code qui pourra être directement converti en documentation Java :

public class Comments {
    /**
     * This is main method of Comments public class. It displays "Test" at your screen.
     * @param String[] args List of arguments you can pass from your terminal.
     * @return void
     */
    public static void main(String[] args) {
        System.out.println("Test");
    }
}

La commande javadoc Comments.java se chargera de générer une documentation Java. Voici ce qu'on recevra :

<!-- ======== START OF CLASS DATA ======== -->
<H2>
Class Comments</H2>
<PRE>
java.lang.Object
  <IMG SRC="./resources/inherit.gif" ALT="extended by "><B>Comments</B>
</PRE>
<HR>
<DL>
<DT><PRE>public class <B>Comments<DT>extends java.lang.Object</DL>
</PRE>

<P>
<HR>

<P>

<!-- ======== CONSTRUCTOR SUMMARY ======== -->

<A NAME="constructor_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Constructor Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><B><A HREF="Comments.html#Comments()">Comments</A></B>()</CODE>

<BR>
           
</TR>
</TABLE>
 
<!-- ========== METHOD SUMMARY =========== -->

<A NAME="method_summary">
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Method Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static void</CODE></FONT></TD>
<TD><CODE><B><A HREF="Comments.html#main(java.lang.String[])">main</A></B>(java.lang.String[] args)</CODE>

<BR>
          This is main method of Comments public class.</TD>
</TR>
</TABLE>
 <A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TH ALIGN="left"><B>Methods inherited from class java.lang.Object</B></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE>clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</CODE></TD>
</TR>
</TABLE>
 

Sur l'écran le rendu est même plus attrayant :

COLLER IMAGE

En analysant le commentaire écrit on remarque la présence des tags précédés par le symbole d'arobase (@). Ces tags ont une signification précise. Voici une liste non exhausive des tags qui pourront être utiles lors du développement des applications en Java :
- @param TYPE NAME : le paramètre passé à la méthode. Après le tag doit se trouver le type du paramètre (String, int etc.) et tout de suite après son nom. Vers la fin on peut rajouter une description du paramètre.
- @return TYPE : le résultat de la méthode. Si la fonction ne retourne rien, le type doit être void. Dans d'autres cas il doit correspondre à la liste des types inclus dans le tag précédent. Comme avant, on peut également rajouter une description plus longue à la suite.
- @author NAME : signifie l'auteur de la méthode, de la classe ou du package.
- @since NAME : permet d'indiquer qu'à partir d'une certaine version il y a un changement de fonctionnement.
- @deprecated : indique que l'usage d'un fragment du code est déconseillé.
- @throws NAME : spécifie quelle exception est captée si l'exécution du code se déroule mal.
- @code CODE_CONTENT : permet d'écrire un code (par exemple HTML) sans pour autant que celui soit traité comme un code exécutable (sera affiché directement dans le navigateur, entre les balises). Un autre tag qui peut faire cela s'appele @literal.
- @link REFERER : ce tag permet de spécifier un lien entre le code présent et celui qui se trouve, par exemple, dans un autre package.
- @inheritDoc : hérite de la documentation la plus proche.
- @link REFERER : ce tag permet de spécifier un lien entre le code présent et celui qui se trouve, par exemple, dans un autre package. Il s'agit probablement du tag le plus sophistiqué à mettre en place. Après le tag on place le package auquel il se réfère. Ensuite on met le symbole "#" suivi du nom de la méthode à laquelle on attache le lien. En gros, cela peut ressembler à ceci : @link Tracker#getTracker(int, String).

Il y a plein d'autres tags mais ceux-ci seront certainement les plus utilisés.

Bartosz KONIECZNY Informations sur le langage

Une question ? Une remarque ?

*

*

Un conseil MySQL

Comment sommer les champs du type TIME ?

La requête suivante devrait être utile :
SELECT SEC_TO_TIME(SUM(TIME_TO_SEC(maColonne))) AS somme FROM nomTableau;