Présentation de l'outil
Installation
Lancement de l'interface graphique
Lancement en ligne de commande
Commentaires extraits du code
Fichier de paramétrage
Limitations et bugs connus
Modification des fichiers générés

What's Up Doc est une application destinée à générer automatiquement de la documentation de développement sur une application programmée en C ou C++.
La documentation générée est en hyper-texte, en syntaxe Html, semblable à la documentation générée par JavaDoc pour Java.
Les principaux éléments de la documentation générée sont :

• un index général
• une page par classe présentant les méthodes et attributs
• une page pour les fonctions globales
• l'arborescence des classes (relations de spécialisation)
• éventuellement les fichiers sources indexés.
• une page présentant les directives de compilation utilisées

Installation
(notes relatives a java)

What's Up Doc doit être exécuté par une machine virtuelle Java. WUD peut donc être exécuté sur n'importe quelle
plate-forme : Windows, Unix ou autre.
Il est bien sur indispensable que l'installation de Java soit correcte et complète.
- L'exécutable de la machine virtuelle (VM ou JVM) doit se trouver dans un des répertoires du chemin de recherche, (contenu
dans la variable d'environnement Path pour le système Windows).
- Le "classpath" doit etre configuré et doit pointer sur les classes de base de Java (rt.jar, classes.zip ou équivalent).

Le nom de l'exécutable java peut varier suivant les versions de java. En conséquence, il est nécessaire d'adapter les fichiers
batch What's Up Doc fournis (wud.bat et gui.bat)

Lancement de What's Up Doc par interface graphique
 

Il suffit de lancer le fichier gui.bat (écrit pour environnement Dos/Windows) apres l'avoir éventuellement adapté à votre environnement java.
 
 

Lancement de What's Up Doc en ligne de commande
 

La syntaxe de lancement de What's up doc est la suivante :
(fichier script wud.bat poour Dos/windows)

wud   [-d <repertoireDestination>]   [-a <repertoireAnalyse>]   [-s <repertoireSource>] [-modifSource] [-noBakSource] [-sourceIndexee]
(chaque option est séparée du répertoire correspondant par un espace)
 

<repertoireDestination>	désigne le chemin dans lequel seront placés les fichiers générés par What's Up Doc
<repertoireAnalyse>	désigne le chemin dans lequel sont placés les fichiers que What's Up Doc doit analyser
<repertoireSource>	désigne le chemin dans lequel peuvent être trouvés les différents fichiers de base utilisés par What's Up Doc (fournis)
-modifSource	indique que WUD peut prendre l'initiative d'ajouter des commentaires évidents à des fonctions qui n'en disposeraient pas
-noBakSource	indique que les fichiers sources ne sont pas sauvegardées avant d'être modifiées (avec -modifSource). Quand ce paramètre n'est pas spécifié, les fichiers sont sauvegardés dans un fichier .Bak
-sourceIndexee	indique qu'il faut générer des sources indexées, c'est à dire une version Html (avec des index) des fichiers sources.

Commentaires dans le code

What's Up Doc analyse les fichiers indiqués, répertorie les classes, méthodes, attributs et fonctions globales.
Il récupère en plus les commentaires associés à ces éléments, pour peu que ceux-ci respectent quelques règles.

What's Up Doc utilise approximativement la même syntaxe de rédaction des commentaires que JavaDoc.
Les commentaires sont pris en compte quand ils précèdent un élément (classe, attribut, méthode ou fonction).
Seuls les commentaires longs (délimités par /* et */) sont utilisés ; les commentaires sur une ligne (précédée par //) sont ignorés.
De plus les commentaires doivent commencer par /** (slash puis deux étoiles) pour être utilisés par What's Up Doc.
Les commentaires longs débutant seulement par /* seront ignorés
Il est possible d'utiliser cette caractéristique (it's not a bug, it's a feature !) pour insérer des commentaires destinés à What's Up Doc et des commentaires qui ne lui sont pas destinés.

Tags supplémentaires :
Il est possible d'insérer des mots clefs dans les commentaires qui permettent d'enrichir la documentation

dans les descriptions suivantes, <element> désigne indiféremment une classe de l'application ou une méthode de la classe courante.

{@link <element>}
Ce tag sera remplacé par un lien Html vers la documentation de l'élément indiqué.
Ce tag peut être inséré au milieu d'une phrase.

@see <element>
Ce tag génère une liste de références à consulter en complément de l'explication précédente, intitulée "voir aussi".
Un lien hyper-texte est généré pour chacun des éléments cités.
Ce tag peut se trouver n'importe où dans le commentaire, il doit se trouver seul sur la ligne (ou la fin de la ligne).
Quelle que soit la place dans le commentaire original, la liste des "voir aussi" est ajoutée à la fin du commentaire généré.

@param <parametre> <explication>
Ce tag génère une liste des paramètres de la méthode.
L'explication continue jusqu'au prochain tag (débutant par @)
Quelle que soit la place dans le commentaire original, la liste des "parametres" est ajoutée à la fin du commentaire généré.

@return <explication>
Ce tag génère simplement une mise en forme particulière.
L'explication continue jusqu'au prochain tag (débutant par @)
Quelle que soit la place dans le commentaire original, le contenu du tag return est ajouté à la fin du commentaire généré.
 

Fichier de paramétrage

WUD gère si vous lui mettait à disposition un fichier de paramétrage.
Ce fichier doit se trouver dans le répertoire source et doit se nommer wud.conf
Ce fichier ne supporte pour le moment qu'un paramètre "nomAppli" qui peut contenir le nom complet du projet.
Ex :
NomAppli = Mon projet à moi qu'il est beau

Limitations et bugs connus

What's Up Doc ne gère pas les directives de compilations.
En règle générale, ceci n'effecte en rien son analyse mais quelques cas particuliers peuvent cependant empêcher l'analyse complète de certaines fichiers sources.

Les liens vers les sources indexées ne sont pas encore 100% opérationnels.
Ces liens seront rendus corrects très prochainement.

Modification des fichiers générés

Il vous est possible de personnaliser les fichiers générés par What's Up Doc, à deux niveaux :

• la mise en forme : couleurs, fontes de caractères
• le contenu : contenu et structure des tables, index, liens etc ...

Modification du contenu
What's Up Doc utilise, pour générer sa documentation, des modèles de pages Html ou de portions de pages. Ces modèles sont rédigés en Html et contiennent des mots-clefs (définis entre crochets) qui sont remplacés dynamiquement par What's Up Doc par les valeurs adéquates au moment de la génération.
En modifiant la localisation de ces mots clefs dans les différents fichiers-modèles, il vous possible de modifier la structure même des fichiers générés.
Les fichiers modèles sont contenus dans le même répertoire que What's Up Doc et portent l'extension Html.