14 févr. 2011

Nice to meet you Javadoc !

Je viens de découvrir Javadoc, qui est un outil permettant de construire la documentation de code en Java. Il faut pour cela se servir de caractères spéciaux qui sont en fait des commentaires -___- de cette forme:



/**
   je suis un commentaire javadoc
*/
Il faut remarquer la deuxieme astérisque dans le commentaire, sans quoi ça restera un commentaire lors du parsage par javadoc. On peut aussi mettre en avant les paramètres des méthodes et les types de retour.

Javadoc permet entre autre de générer une documentation au format HTML framé, doc ou même pdf. Sa force est dans le fait que l'on documente au fur et à mesure que l'on code. La doc étant générée post codage, on aura pas à revenir en arrière et perdre du temps si on sait plus ce que telle ou telle méthode faisait.

Je ne sais pas si c'est vraiment ça, et je demanderais au prof, mais j'ai l'impression que javadoc est un peu l'étape préprocessing à l'instar du C ou d'objective-C avec ses "@".

Le lien ultime, pour se documenter sur la javadoc, ICI.

Pour l'exemple, j'utilise javadoc comme cela:
javadoc -charset "UTF-8" -d doc -classpath classes -sourcepath src fr.unice.wp803469.employe
le flag charset est très utile car il permet de s'affranchir de l'écriture au format HTML des caractères non ASCII mais Unicode :D

Evidement, il est préférable de voir l'arborescence de mon projet pour avoir une meilleure idée de quoi la commande est composée...

(et ca me permet de vous introduire à tree, comande unix carement indispensable qui permet d'avoir une vue arborescente d'un répertoire, une sorte de ls pour windowsien. Il est trouvable dans toutes les bonnes épiceries comme apt-get ou macports entre autres):

MacBook-de-Paraita-Wohler% tree
.
├── Paie.class
├── Paie.java
├── TestArticle.class
├── TestArticle.java
├── TestEmploye.class
├── TestEmploye.java
├── classes
│   └── fr
│       └── unice
│           └── wp803469
│               ├── article
│               │   ├── Article.class
│               │   ├── Articleable.class
│               │   ├── Lot.class
│               │   ├── Ramette.class
│               │   ├── Stylo$couleurs.class
│               │   └── Stylo.class
│               ├── employe
│               │   ├── Commercial.class
│               │   ├── Employe.class
│               │   ├── EmployeDeBase.class
│               │   └── Manager.class
│               └── facture
│                   ├── Facturable.class
│                   ├── Facture.class
│                   └── FactureItem.class
├── doc
│   ├── allclasses-frame.html
│   ├── allclasses-noframe.html
│   ├── constant-values.html
│   ├── deprecated-list.html
│   ├── fr
│   │   └── unice
│   │       └── wp803469
│   │           └── employe
│   │               ├── Commercial.html
│   │               ├── Employe.html
│   │               ├── EmployeDeBase.html
│   │               ├── Manager.html
│   │               ├── package-frame.html
│   │               ├── package-summary.html
│   │               └── package-tree.html
│   ├── help-doc.html
│   ├── index-all.html
│   ├── index.html
│   ├── overview-tree.html
│   ├── package-list
│   ├── resources
│   │   └── inherit.gif
│   └── stylesheet.css
└── src
    └── fr
        └── unice
            └── wp803469
                ├── article
                │   ├── Article.java
                │   ├── Article.java~
                │   ├── Articleable.java
                │   ├── Articleable.java~
                │   ├── Lot.java
                │   ├── Lot.java~
                │   ├── Ramette.java
                │   ├── Ramette.java~
                │   ├── Stylo.java
                │   ├── Stylo.java~
                │   └── TestArticle.java~
                ├── employe
                │   ├── Commercial.java
                │   ├── Commercial.java~
                │   ├── Employe.java
                │   ├── Employe.java~
                │   ├── EmployeDeBase.java
                │   ├── EmployeDeBase.java~
                │   ├── Manager.java
                │   └── Manager.java~
                └── facture
                    ├── Facturable.java
                    ├── Facturable.java~
                    ├── Facture.java
                    ├── Facture.java~
                    ├── FactureItem.java
                    └── FactureItem.java~
20 directories, 62 files

Aucun commentaire: