La documentation est une ressource précieuse pour comprendre et appréhender une librairie, une api, ou un projet. 
Il existe différents formats de documentation adaptés à différents besoins. Pour le langage Java, la ressource principale est la Javadoc. 

Celle-ci est générée directement à partir du code. Elle se base sur des commentaires et annotations particulières et adopte une template spécial. 

Ce template n'a quasiment pas évolué depuis sa création. La manière de naviguer est toujours la même. récemment, la CSS a évolué pour donner un coup de jeune (et aussi marquer le passage de Sun à Oracle).

J'évoquais précédemment que la navigation au sein de la documentation n'a pas évolué. Après un certain temps d'utilisation on arrive à retrouver (ou découvrir) les informations cherchées. Néanmoins, le côté très statique implique de bien connaitre sa structure et ne permet pas d'accéder rapidement à une information inconnue. 

Par exemple, si un collègue vous indique le nom d'une méthode d'une classe répondant à la problématique à laquelle vous êtes confronté depuis quelques semaines . S'il ne vous précise pas les informations sur le package ou le nom de la classe, il va falloir chercher et tâtonner (exemple tiré un peu par les cheveux 🙂 ).

Les nouveautés arrivent avec les nouveaux langages tournant sur la JVM. Par exemple le langage Scala (comme par hasard…) propose des fonctionnalités intéressantes et pratiques au sein de sa documentation (scaladoc). En effet, la scaladoc met à disposition deux moteurs de recherche. 
le premier permet de rechercher dans les types (soit en tapant le nom du type, ou en sélectionnant la première lettre du type recherché).
Le deuxième permet de faire une recherche directement au sein d'un type sur les fonctions qui le compose.

Une nouvelle approche est mise en place par le projet 
nommé Scalex. Ce projet propose de manipuler la documentation au travers d'une recherche fulltext. Cette approche permet d'être (selon moi) beaucoup plus efficace dans l'utilisation de la documentation sous-jacente.
Pour l'instant, le projet permet d'accéder à deux indexes de documentation : 

Scala 2.9.1-1
Scalaz 6.0.4

La recherche se fait à partir de l'expression de mots ou alors à l'aide d'un pseudo langage permettant d'affiner sa recherche.

L'outil propose plusieurs moyens pour l'utiliser (ou s'interfacer). Le service est accessible via : 
-La ligne de commande
-IRC
-Web (javascript)
-XMPP
-SBT

Scalex s'est inspiré de Hoogle, le moteur utilisé pour Haskell.

Vous trouverez l'accès au moteur de recherche ainsi qu'à des détails sur le pseudo-langage en regardant le lien attaché à ce post.

#java #documentation #javadoc #scalex.