Location: PHPKode > projects > JaPHPaDoc > developers.txt
        *************************
        * Note aux développeurs *
        *************************

  Ce projet est sous licence GNU-GPL.
  Vous pouvez donc participer au développement, si vous souhaitez faire avancer
le projet plus rapidement.

  Pour ce faire vous devez avoir connaissance de quelques éléments concernant
l'organisation du logiciel dans sa version actuelle.

  Ce document a pour but de vous expliquer le fonctionnement interne de
JaPHPaDoc afin de vous aider a l'améliorer en vous appropriant son mode de
travail rapidement.



   1. Les fichiers
      ============

  Le programme est fourni sous forme d'une archive contenant l'arborescence
suivante:

[japhpadoc]               ## Répertoire d'installation
|                         ##
+- readme.txt             ## fichier d'explication
+- developers.txt         ## ce fichier
+- todo.txt               ## modifications a apporter
+- changelog.txt          ## historique des versions
+- install.bat            ## script d'appel a la procedure d'installation
|                         ##
+- [documentation]        ## répertoire contenant la documentation des classes
|                         ##
+- [php-files]            ##
   |                      ##
   +- CommandLine.inc     ## classe de la manipulation de la ligne de commande
   +- MyPhpDoc.inc        ## classe de génération de la japhpadoc
   +- japhpadocMain.inc   ## fonctions main
   +- Process.inc         ## classe de manipulation de processus
   +- install.php         ## script d'installation

  Durant l'installation, les fichiers suivants sont générés:

[japhpadoc]               ## répertoire d'installation
|                         ##
+- japhpadoc.bat          ## script d'appel du générateur
|                         ##
+- [php-files]            ##
   |                      ##
   +- japhpadoc.php       ## script d'appel des fonctions de génération
   +- config.inc          ## configuration

  Des fichiers temporaires sont également générés mais devraient être effacés.
  Après l'installation les fichier install.bat et php-files/install.php peuvent
être supprimés.



   2. Installation
      ============

  L'installation demande quelques informations nécessaires (chemin vers la
version CGI de php, vérification de la version, de la présence de javadoc,
etc...) et crée grace a ces informations les fichiers principaux.

  Le script d'appel de l'installeur "install.bat" ne fait quasiment rien, il
appelle simplement "install.php" et je vous encourage vivement a consulter ce
fichier pour voir comment sont générés les fichiers, et pourquoi (et comment) on
vérifie et qu'on demande ces informations.



   3. Rôle des fichiers
      =================

  CommandLine.inc contient une classe de manipulation de la ligne de commande.
  Process.inc contient une classe pour lancer des commandes systeme.
  MyPhpDoc contient une classe particulière. Cette classe est la génératrice de
JaPHPaDoc principale. Elle est nommée ainsi car dans les premieres heures je
voulais nommer ce projet MyPhpDoc. Finalement le projet est renommé mais pas
cette classe: cela changera probablement.

  La documentation de ces classes se trouve normalement dans le répertoire
'documentation'. Si elle ne s'y trouve pas, pour la générer:
"japhpadoc -f php-files\*.inc -author -version -v -d documentation"
  Cette documentation ne génère que la documentation des méthodes publiques.
Pour générer la doc des méthodes privées également (vous pourriez en avoir
besoin durant vos phases de développement):
"japhpadoc -f php-files\*.inc -author -version -v -d documentation -private"

  Le dernier fichier auxiliaire se nomme japhpadocMain.inc. Il regroupe non des
classes mais des fonctions, dont la fonction main() qui démarre le programme.

  De nombreuses constantes sont utilisés dans les différents fichiers, il est
donc primordial de comprendre leur cycle de vie dans le programme.
Actuellement le voici:

Création:
config.inc        -> APP_NAME,APP_VERSION,APP_AUTHOR,INC_DIR,PHP_EXE,DIR_SEP
japhpadocMain.inc -> VERBOSE,SHOW,DEST_DIR,OPT_AUTHOR,OPT_VERSION,OPT_USE

config.inc n'utilise aucune constante (il ne fait que définit).
japhpadocMain.inc n'utilise que les constantes définies par config.inc
MyPhpDoc.inc utilise les constantes définies par ces trois fichiers.
CommandLine.inc et Process.inc n'utilisent pas ces constantes.

  C'est pourquoi l'ordre d'inclusion est important:
"config.inc" doit etre inclus avant tout (il est inclus en premier dans
japhpadoc.php en premier) car il définit INC_DIR qui permet d'inclure en absolu
les fichiers nécessaires dans les scripts suivants.



   4. Fonctionnement interne
      ======================

  Le programme fonctionne pour l'instant de la manière suivante:

1. vérification des options.
2. vérification de la syntaxe pour les fichiers.
3. appel de la fonction principale: MyPhpDoc::generate() avec la liste des
   fichiers récupérés.
4. Pour chacun des fichiers on effectue les opérations suivantes:
   4.1. On parse le source, pour éliminer le code inutile (on ne garde que les
        déclaration et la japhpadoc).
   4.2. On parse ce code épuré pour en extraire une structure de données proche
        de PHP.
   4.3. On transforme cette structure en une forme plus proche de java (on
        déplace les éléments de la doc vers les méthodes/attributs).
   4.4. On produit du code java dans des fichier *.java temporaires.
5. On génère la documentation a partir de ces fichiers, par un appel de javadoc.
6. On supprime les fichiers temporaires.

  La première amélioration à apporter pourrait être de réduire la phase 4 en une
seule passe. C'est tout-a-fait possible, mais j'ai préféré ne pas le faire, car
cela nuirait profondément à la lisibilité et la maintenance du code. Il s'agit
donc d'une amélioration que je souhaite, mais que je souhaite tardive.






Return current item: JaPHPaDoc