[php5] classe de documentation de classes et de fonctions

Soyez le premier à donner votre avis sur cette source.

Vue 11 819 fois - Téléchargée 659 fois

Description

CREDITS

A very special thanks to Bastian Gorke for his contribution, he added the German translation!
Thanks a lot, Bastian! :-)

Un grand merci à Bastian Gorke pour sa contribution, il a ajouté la traduction en allemand!
Merci beaucoup, Bastian! :-)

README

Ce script est un script de documentation de classes et de fonctions.
L'utilisation est très simple :

CLASSES :
Leur analyse fonctionne par package.
Un formulaire sert à créer un package.
Un autre sert à uploader des classes dans un package. Si vous avez des classes héritant d'autres classes,
vous devez uploader ces classes parentes dans le package.
Un 3ème forumaire, enfin, sert à analyser le package complet.
Une documentation sera créée, avec un index propre au package, contenant le diagramme d'héritages du package.

FONCTIONS :
Un formulaire sert à uploader le fichier de fonction, un autre à analyser les fichiers uploadés.
Seules les fonctions 'user_defined' seront analysées.

Une collection de fichiers html sont alors créés, facilement transportable dans un autre script
donc on veut documenter les classes ou/et fonctions.

A noter que l'on peut analyser n'importe quelle classe, y compris une classe interne.

La documentation est localisée. Pour le moment, sont supportés l'anglais, le français et l'allemand.
Il est très facile de créer une traduction : il suffit de rajouter une langue dans les fichiers xml
qui se trouvent dans le répertoire 'locales'.

J'ai mis dans le répertoire css/ différentes css, pour montrer que le design est très facilement
modifable. Il suffit pour cela de nommer la css voulue "maindoc.css".

index.php passe par l'interface utilisateur
index2.php montre comment ne pas passer par cette interface (il faut au prélable mettre les classes
à documenter dans le répertoire 'classes')

REPERTOIRES :

class/ => contient les classes faisant fonctionner le script : odocclass.cls.php, odocfunc.cls.php, olocale.cls.php et ohtml.cls.php
classes/ => contient les classes à analyser
fonctions/ => contient les fichiers de fonctions à analyser
css/ => contient la css de la documentation
docs/"langue"/"package"/classes/ et docs/"langue"/fonctions/ => lorsque une classe ou une fonction est analysée, ce répertoire est créé, ainsi qu'un sous-répertoire
du nom de la classe/fonction étudiée. Dans ce sous-répertoire se trouvent les fichiers
html de la documentation
locales/ => contient les fichiers xml de localisation

This script is a classes and functions documentation tool.
It's easy to use :

CLASSES :
Their analysis is based on packages.
A first form is used to create a package name.
A second one is used to upload classes in the package. If you have inherited classes, you MUST upload these
parent classes in the package, too.
A thirs form, finally, is used to analyze a chosen package.
The documentation is then created, with an index page for the package, displaying a diagram for the classes hierarchy.

FONCTIONS :
A first form is used to upload the functions files, and a second one to analyze the chosen file.

HTML files are then created, you can easily move wherever you want to give access to the documentation.

The documentation tool is localized : up to now, only English, French and German are supported.
But it is very easy to create a new language : you just have to translate all the xml files located in the folder 'locales'.
Then, just add the nez language button in the file 'localize.form.html'.

I have put in the 'css' folder various css. The one used will be the one named 'maindoc.css'.
You can create yours quite easily.

FOLDERS :
class/ => here are the tool classes : odocclass.cls.php, odocfunc.cls.php, olocale.cls.php and ohtml.cls.php
classes/ => here are the uploaded classes to be analyzed
fonctions/ => here are the uploaded functions files to be analized
css/ => here are the css files (maindoc.css being the one currently used)
docs/'language_name'/"package_name"/classes and docs/'language_name'/fonctions => here are the html documentation files
locales/ => here are the xml translation files

Source / Exemple :


<?php
/**

  • CLASS odocclass
  • classe de documentation de classes
  • @auteur : johan <barbier_johan@hotmail.com>
  • @version : 2.4
  • @date : 2006/02/10
*
  • free to use, modify, please just tell me if you make any changes :-)
  • /
class odocclass extends ReflectionClass { /**
  • propriété qui contiendra l'objet olocale pour la localisation
  • /
private $oloc; /**
  • tableau des propriétés générales
  • /
private $aGeneral = array (); /**
  • tableau des propriétés des méthodes
  • /
private $aMethods = array (); /**
  • tableau des propriétés des propriétés
  • /
private $aProperties = array (); /** /**
  • tableau buffer des lignes des fichiers codes
  • /
private $fileBuf = array (); /**
  • tableau des classes et de leurs enfants d'un package
  • /
private $aChild = array (); /**
  • chaîne qui contiendra le nom du package
  • /
private $package = ''; /**
  • constructeur
  • @Params string className : nom de la classe à analyser
  • @Params string child : nom de la classe fille appelante, héritant de la classe courante
  • /
public function __construct ($package, array $aArbo) { $this -> oloc = new olocale ($_SESSION['locale']); $this -> package = $package; $this -> aArbo = $aArbo; foreach ($this -> aArbo as $className => $dump) { $this -> aChild[$className]['children'] = array (); foreach ($aArbo as $clef => $val) { if ($className === $val['parent']) { $this -> aChild[$className]['children'][] = $clef; } } parent::__construct ($className); $this -> aGeneral = $this -> getGeneral (); $this -> aMethods = $this -> getaMethods (); $this -> aProperties = $this -> getaProperties (); if (empty ($this -> aGeneral['classe'])) { if (empty ($this -> aArbo[$className]['parent'])) { $parent = ''; } else { $parent = $this -> aGeneral['classe'] = $this -> aArbo[$className]['parent']; $this -> aGeneral['classeType'] = 'interface'; } } else { $parent = $this -> aGeneral['classe']; } $this -> aChild[$className]['parent'] = $parent; $this -> buildHtmlClass (); } $ohtml = new ohtml ($this -> package); $ohtml -> setIndexPack ($this -> aChild); } /**
  • méthode privée buildHtmlClass
  • appelle l'objet ohtml pour construire effectivement la doc pour les classes
  • /
private function buildHtmlClass () { $ohtml = new ohtml ($this -> package); $ohtml -> header (); $ohtml -> setMenu ($this -> aGeneral['name'], $this -> aGeneral['classe'], $this -> aChild[$this -> aGeneral['name']]['children'], $this -> aMethods, $this -> aProperties); $ohtml -> setContentGeneral ($this -> aGeneral); $ohtml -> footer (); $ohtml -> toFileClass ($this -> aGeneral['name'], $this -> aGeneral['name']); $ohtml -> freeHtml (); foreach ($this -> aMethods as $clef => $val) { $ohtml -> header (); $ohtml -> setMenu ($this -> aGeneral['name'], $this -> aGeneral['classe'], $this -> aChild[$this -> aGeneral['name']]['children'], $this -> aMethods, $this -> aProperties, $clef); $ohtml -> setContentMethods ($val); $ohtml -> footer (); $ohtml -> toFileMethProps ($this -> aGeneral['name'], $clef); $ohtml -> freeHtml (); } foreach ($this -> aProperties as $clef => $val) { $ohtml -> header (); $ohtml -> setMenu ($this -> aGeneral['name'], $this -> aGeneral['classe'], $this -> aChild[$this -> aGeneral['name']]['children'], $this -> aMethods, $this -> aProperties, $clef); $ohtml -> setContentProperties ($val); $ohtml -> footer (); $ohtml -> toFileMethProps ($this -> aGeneral['name'], $clef); $ohtml -> freeHtml (); } $ohtml -> setIndex (); } /**
  • méthode privée getCode
  • sert à récupérer le code dans un fichier, d'une ligne de départ jusqu'à 1 ligne d'arrivée
  • @Return : string code
  • /
private function getCode ($filename, $start, $end) { $code = ''; if (!empty ($filename)) { if (!array_key_exists ($filename, $this -> fileBuf)) { $this -> fileBuf[$filename] = file ($filename); } for ($i = $start - 1; $i <= $end; $i++) { $code .= $this -> fileBuf[$filename][$i]; } } return $code; } /**
  • méthode privée getGeneral
  • sert à remplir le tableau des propriétés générales de la classe à analyser
  • @Return : array aTmp
  • /
private function getGeneral () { $aTmp['name'] = $this -> getName (); $aTmp['type'] = $this -> isInternal () ? 'internal' : 'user-defined'; $aTmp['abstract'] = $this -> isAbstract () ? 'abstract' : ''; $aTmp['interface'] = $this -> isInterface () ? 'interface' : 'class'; $aTmp['file'] = $this -> getFileName(); $aTmp['startline'] = $this -> getStartLine(); $aTmp['endline'] = $this -> getEndLine(); $aTmp['code'] = utf8_encode ($this -> getCode ($aTmp['file'], $aTmp['startline'], $aTmp['endline'])); $aTmp['final'] = $this -> isFinal () ? ' final' : ''; $aTmp['comments'] = method_exists ($this, 'getDocComment')?utf8_encode (htmlentities($this -> getDocComment ())):$this -> oloc -> getMsg ('errors', 'php_bad_version'); $aTmp['total methods'] = count ($this -> getMethods ()); $aTmp['total properties'] = count ($this -> getProperties ()); $parent = $this -> getParentClass(); if (is_object ($parent)) { $name = $parent -> getName (); $parentType = $parent -> isInterface ()?'interface':'class'; } else { $name = ''; $parentType = ''; } $aTmp['classe'] = $name; $aTmp['classeType'] = $parentType; if (!empty ($aTmp)) { return $aTmp; } else { return array (); } } /**
  • méthode privée getMethods
  • sert à remplir le tableau des propriétés des méthodes de la classe à analyser
  • @Return : array aTmp
  • /
private function getaMethods () { foreach ($this -> getMethods () as $val) { $aTmp[$val -> getName ()] = array ( 'name' => $val->getName (), 'type' => $val->isInternal() ? 'internal' : 'user-defined', 'abstract' => $val->isAbstract() ? ' abstract' : '', 'final' => $val->isFinal() ? ' final' : '', 'public' => $val->isPublic() ? ' public' : '', 'private' => $val->isPrivate() ? ' private' : '', 'protected' => $val->isProtected() ? ' protected' : '', 'static' => $val->isStatic() ? ' static' : '', 'constructor' => $val->isConstructor()?'constructor':($val -> isDestructor()?'destructor':'regular method'), 'file' => $val->getFileName(), 'startline' => $val->getStartLine(), 'endline' => $val->getEndline(), 'code' => utf8_encode ($this -> getCode ($val->getFileName(), $val->getStartLine(), $val->getEndline())), 'modifiers' => $val->getModifiers(). ' => '.implode(' ', Reflection::getModifierNames($val->getModifiers())), 'comments' => method_exists ($val, 'getDocComment')?utf8_encode (htmlentities($val -> getDocComment ())):$this -> oloc -> getMsg ('errors', 'php_bad_version'), 'statics' => $val->getStaticVariables(), 'classe' => $val -> getDeclaringClass() -> getName (), 'parameters' => $this -> getaParameters ($val -> getParameters()) ); $aTmp[$val -> getName ()]['returns'] = $this -> getReturns ($aTmp[$val -> getName ()]['comments']); $aTmp[$val -> getName ()]['params'] = $this -> getParams ($aTmp[$val -> getName ()]['comments']); } if (!empty ($aTmp)) { return $aTmp; } else { return array (); } } /**
  • méthode privée getReturns
  • sert à récupérer le code pour la/les valeur/s de retour de la méthode, si elle est documentée
  • @Param string comments : contient une chaîne avec les commentaires de la méthode
  • @Return array aTmp : contient un tableau avec les retours possibles
  • /
private function getReturns ($comments) { preg_match_all ('@\@return[s]?+(.+)@im', $comments, $res); $aTmp = $res[1]; return (array)$aTmp; } /**
  • méthode privée getParams
  • sert à récupérer le code pour le/les paramètre/s de la méthode, si elle est documentée
  • @Param string comments : contient une chaîne avec les commentaires de la méthode
  • @Return array aTmp : contient un tableau avec les paramètres possibles
  • /
private function getParams ($comments) { preg_match_all ('@\@param[s]?+(.+)@im', $comments, $res); $aTmp = $res[1]; return (array)$aTmp; } /**
  • méthode privée getaParameters
  • sert à remplir le tableau des paramètres des méthodes
  • @Return : array aTmp
  • /
private function getaParameters ($aArgs) { $aTmp = array (); if (!empty ($aArgs)) { foreach ($aArgs as $val) { $isArray = true === method_exists ($val, 'isArray')?$val -> isArray():false; $aTmp[$val -> getName ()] = array ( 'name' => $val -> getName (), 'reference' => $val -> isPassedByReference()?'&':'', 'array' => ($isArray)?'array':'', 'optional' => $val -> isOptional()?$this -> oloc -> getMsg ('doc', 'doc_optional'):$this -> oloc -> getMsg ('doc', 'doc_mandatory'), 'default' => ($val -> isDefaultValueAvailable())?$val -> getDefaultValue():'' ); } } if (!empty ($aTmp)) { return $aTmp; } else { return array (); } } /**
  • méthode privée getGeneral
  • sert à remplir le tableau des propriétés des propriétés de la classe à analyser
  • @Return : array aTmp
  • /
private function getaProperties () { foreach ($this -> getProperties () as $val) { $aTmp[$val -> getName ()] = array ( 'name' => $val->getName (), 'public' => $val -> isPublic()?'public':'', 'private' => $val -> isPrivate()?'private':'', 'protected' => $val -> isProtected()?'protected':'', 'static' => $val -> isStatic()?'static':'', 'default' => $val -> isDefault()?$this -> oloc -> getMsg ('doc', 'doc_yes'):$this -> oloc -> getMsg ('doc', 'doc_no'), 'modifiers' => $val->getModifiers(). ' => '.implode(' ', Reflection::getModifierNames($val->getModifiers())), 'comments' => method_exists ($val, 'getDocComment')?utf8_encode (htmlentities ($val -> getDocComment ())):$this -> oloc -> getMsg ('errors', 'php_bad_version'), 'classe' => $val -> getDeclaringClass() -> getName (), 'code' => utf8_encode ($this -> getPropsCode ($val -> getDeclaringClass() -> getFileName (), $val -> getName())), ); $aTmp[$val -> getName ()]['defaultvalue'] = ltrim (strstr ($aTmp[$val -> getName ()]['code'], '='), '='); } if (!empty ($aTmp)) { return $aTmp; } else { return array (); } } /**
  • méthode privée getPropsCode
  • sert à récupérer la portin de code où est définie une propriété donnée
  • @Params string fileName : nom du fichier où est définie la propriété
  • @Params string name : nom de la propriété
  • @Return : string code en cas de succès, false en cas d'échec
  • /
private function getPropsCode ($fileName, $name) { if (!empty ($fileName)) { if (!array_key_exists ($fileName, $this -> fileBuf)) { $this -> fileBuf[$fileName] = file ($fileName); } $cpt = count ($this -> fileBuf[$fileName]); for ($i = 0; $i < $cpt; $i++) { if (false !== strpos ($this -> fileBuf[$fileName][$i], $name)) { $start = $i; break; } } if (isset ($start)) { for ($i = $start; $i < $cpt; $i++) { if (false !== strpos ($this -> fileBuf[$fileName][$i], ';')) { $end = $i; break; } } } if (isset ($end) && isset ($start)) { $code = ''; for ($i = $start; $i <= $end; $i++) { $code .= $this -> fileBuf[$fileName][$i]; } return $code; } } return false; } } ?>

Conclusion :


Ci-dessus, uniquement la classe odoc.
Le zip contient le script complet, et un fichier readme.txt pour l'aide.

Codes Sources

A voir également

Ajouter un commentaire

Commentaires

cs_Anthomicro
Messages postés
9433
Date d'inscription
mardi 9 octobre 2001
Statut
Membre
Dernière intervention
13 avril 2007
8 -
C'est excellent quand je vois la capture (voir mon autre commentaire sur codes-php). je mets 10 sans hésitation.
neojet
Messages postés
7
Date d'inscription
mercredi 5 mai 2004
Statut
Membre
Dernière intervention
24 août 2006
-
Le titre aussi est pas mal ;-)
malalam
Messages postés
10843
Date d'inscription
lundi 24 février 2003
Statut
Modérateur
Dernière intervention
2 mars 2010
17 -
Lol, la capture, le titre...qui a dit que pour plaire, fallait un bon code bien structuré, efficace, et qui tourne?? Naaan, un joli titre, une capture qui le fait...et z'avez 10 !! ;-)

Antho => je regerderai ce matin pour ton problème avec ce code...parce qu'en local je tourne aussi sous wamp, en php 5.1, et ça marche. Idem sur un des serveurs de prod, en php 5.1 aussi.
Donc je suis très étonné par la réaction de ton serveur devant mon code ;-) Je vais sans doute tester l'existence des méthodes avant de les lancer, dans ce cas...chais pas trop encore :-)
superbaloo78
Messages postés
87
Date d'inscription
vendredi 29 août 2003
Statut
Membre
Dernière intervention
19 mai 2006
-
Salut,
malalam il est de toi ce script (j'ai pas regardé le code :D) ? parce que j'ai deja entendu parlé d'un gros projet qui permettait justement de documenter ses classes (c'est l'equivalent de phpmyadmin mais pour les classes en faite ...)

j'essayerai de retrouver le lien si j'ai le temps ...

Superbaloo
superbaloo78
Messages postés
87
Date d'inscription
vendredi 29 août 2003
Statut
Membre
Dernière intervention
19 mai 2006
-
http://phpmanta.sourceforge.net/

mais c'est peut-etre un peu plus usine à gaz que le tien .... je sais pas j'ai pas essayé

Vous n'êtes pas encore membre ?

inscrivez-vous, c'est gratuit et ça prend moins d'une minute !

Les membres obtiennent plus de réponses que les utilisateurs anonymes.

Le fait d'être membre vous permet d'avoir un suivi détaillé de vos demandes et codes sources.

Le fait d'être membre vous permet d'avoir des options supplémentaires.