Discussion :

[Nonothehobbit]

=== Rajouté par cyberzoide ===
Ce thread a permis de réaliser le :
Comparatif des générateurs de documentation PHP
========================



Connaissez-vous un générateur de doc php ?
Et en français ce serait le must même si je rechigne pas sur l'anglais.

J'utilise actuellement phpdoc : http://www.phpdoc.de mais le développement s'est arrêté.

Donc selon vous quel est le meilleur des générateurs de doc ? J'ai commencé une recherche, je vous dirais ce que j'ai trouvé mais bon, si quelqu'un à déjà des trucs...

[Nonothehobbit]

Définitivement : www.phpdoc.org/

Ce prog est une tuerie ! J'adore.

[xmag]

Définitivement : www.phpdoc.org/

Ce prog est une tuerie ! J'adore.

Salut,

Je l'ai testé et il n'arrive jamais à la fin de la génération... pourtant, j'ai en gros 30 fichiers...
Il m'écrit des erreurs du type :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

ERROR in utilisateur.php on line 34: @access was passed neither "public" nor "private."  Was passed: "public

et

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

WARNING in utilisateur.php on line 375: File "C:\web\intranet\classes\utilisateur.php" has no page-level DocBlock, use @package in the first DocBlock to create one

Y a t-il quelque chose à modifier dans mes classes ou dans la config de phpDocumentor?

Merci d'avance ;-)

[Nonothehobbit]

Pour les warning, j'ai les même mais ça passe quand même, ça ne l'empêche pas de générer. Pour ton erreur, tu dois avoir un problème avec tes tags @access. Regarde l'aide du générateur pour en savoir plus...

[xmag]

Pour ton erreur, tu dois avoir un problème avec tes tags @access. Regarde l'aide du générateur pour en savoir plus...

Ben ils disent de les mettre de cette manière :

@access private protected public

et dans ma classe, c'est comme ça :

/***
* Commentaire
* @param str $strNom
*
* @return boo Connecté ou non
*
* @access public
*
***/

Tu vois un truc bizarre?

[xmag]

En fait, quand je vais un @access en haut de ma classe, il ne met pas d'erreur, mais quand j'en mets au dessus de mes methodes, il me met une erreur...

[Nonothehobbit]

Oui : j'ai testé en copiant/collant ton commentaire sur une méthode d'une classe bidon et tout passe bien.

[cedricgirard]

Question : a quoi ça sert une doc automatique? Un ami dit qu'elle est juste bonne à être lue automatiquement, donc pas vraiment par un humain qui réfléchit.
La meilleure doc est le code lui même. Pourtant je bosse sur plusieurs gros projets. Autant un browser de code me semble neccessaire, autant la doc me semble sujette à être toujours en retard sur le code.

Cédric

[xmag]

Question : a quoi ça sert une doc automatique?

Et bien moi, j'aimerais m'en servir pour avoir un accès facile à tous les objets développés qui peuvent être réutilisables pour d'autres projets...

[Nonothehobbit]

Mmmm c'est pas pour dire mais j'ai essayé de générer une doc avec phpEdit, j'ai déjà pas mal galéré pour trouver comment faire apparemment il faut éditer un script et tout houlala c'est "userfriendly" comme dirait l'autre.

Je resterais donc à phpdocumentor qui me prend pas la tête et me génère tout en 2 clics.

[Curtis]

Question : a quoi ça sert une doc automatique?

Ben ca set aussi a avoir une documentation AUTOMATIQUEMENT à jour
en fonction des développement.

De plus cela oblige à avoir un certaine rigueur dans les commentaires
(mettre un commentaire pour chaque classe,
mettre un commentaire pour chaque fonction )

et donc lorsque l'on développe àplusieur cela permet de connaitre
les fonctions créées par les autres utilisteurs pour pouvoir
les utiliser rapidement sans avoir à se palucher tout le code à lire.

Personnellement j'utilise avec bonheur doxygen (!) sur mon code
php et cela se passe très bien .

[Nonothehobbit]

Imagine aussi que tu crypte tes source avec zend optimizer par exemple... L'utilisateur n'aura plus accès à tes sources, il ne restera plus que la doc.

Un autre exemple plus courant : tu veux faire partager une ou plusieurs classe ) d'autre personnes ou tu travaille sur un projet à plusieurs. Il est beaucoup plus simple pour l'utilisateur de test classes / fonctions d'aller voir une doc en ligne plutot que d'ouvrir le fichier et de faire fumer la roulette. (expression pour dire "chercher des heures où se trouve une méthode")

[cedricgirard]

Ce que je veux dire, c'est que la documentation automatique est un palliatif à un code que l'on ne peut mémoriser completement non?
Un code clair et propre a t'il besoin de documentation de code? D'une documentatiion d'architecture OK, mais de documentation du code?
Un code bien nommé se mémorise facilement. Ensuite ok quand on arrive sur un projet non connu un navigateur de code est utile, mais la doc ne sera bonne que si les developpeurs ont pris la peine de travailler pour...

Que va donner la doc de code? La liste des fonctions avec les parametres, qq commentaire sur son uasage? Cela peut être obtenu avec un editeur capable de parser les fichier et de completer la saisie, d'afficher les parametres comme le fait PHPEdit par exemple, ou Eclispe.
Une fonction qui a besoin d'une commentaire pour être comprise est elle bien nommée? Ses parametres ne sont ils pas trop nombreux?
Surtout le carcan des commentaires ne va t'il pas empecher que cette fonction soit par exemple découpée en plusieurs autres, pour la rendre compréhensible?

Le but est d'être efficace quand on code, pas d'écrire de la documentation - car le générateur de doc ne fait que centraliser les commentaires, donc à la base c'est le dévellopeur qui travaille, pas l'outils.

Et je le repete, je travaille sur d'assez gros projet (un CMS PHP de 27000 lignes - à faire maigrir - ou un projet pro de controle de machines/pompes en Delphi)

[Nonothehobbit]

Si t'es tout seul sur ton projet et que t'arrives à totu avoir dans la tête ok, mais quand tu travailles à plusieurs, la doc est quasiment indispensable car elle permet d'avoir rapidement les infos sur une classe/fonction/variable. Quand aux noms de fonctions qui s'autocommente c'est une utopie, on a souvent besoin de précision sur la gestion de cas particulier par exemple.
De plus avec php on indique pas le type des paramètres que l'on veux utiliser, seuls les commentaires et donc la doc permettent de le savoir...

Tu imagines toi aller dans le code source de php pour savoir comment marche une fonction ???? Moi je dis vive la doc.

[cedricgirard]

Imagine aussi que tu crypte tes source avec zend optimizer par exemple... L'utilisateur n'aura plus accès à tes sources, il ne restera plus que la doc.

Un autre exemple plus courant : tu veux faire partager une ou plusieurs classe ) d'autre personnes ou tu travaille sur un projet à plusieurs. Il est beaucoup plus simple pour l'utilisateur de test classes / fonctions d'aller voir une doc en ligne plutot que d'ouvrir le fichier et de faire fumer la roulette. (expression pour dire "chercher des heures où se trouve une méthode")

Dans ce cas ok, mais c'est une doc utilisateur, externe. Et encore est il souvent plus efficace d'aller voir le code tellement certaines doc sont cryptique. Je parle de doc interne, pour l'équipe de dev, ou à destination d'un nouvel arrivant dans l'équipe. Peux t'il comprendre le projet avec des docs sur le code? Je ne le crois pas.

Dans une boite, on m'a donné le premier jour le MCD et la norme de codage. Ai je compris qq chose d'utile pour mon travail les jours suivants? Non. C'était pourtant une doc générée automatiquement à partir de la DB, et une doc rédigée avec soin sur comment coder.
En parcourant la base de données, en regardant les données réelles en exploitation, la j'ai compris. Ce qui me fait dire que le MCD était mauvais, car pas clair.

[baptistoux]

J'utilise Doxygen pour générer la docmentation de mes développments en C++ ce qui me convient parfaitement.
Cependant j'ai un problème avec ce même outil quand je désire générer la doc pour une application php5; je m'explique :
Doxygen ne me génère la documentation des classes mères, mais pas celle des classes qui en dérive
Quelqu'un aurai rencontré un problème similaire ???

Sinon phpDocumentor génère t-il la documentation en français ?

[Epoc22]

désolé baptistoux, je peut pas t'aider mais les personnes d'en haut le peuvent certainement...
En ce qui concerne PhpDocumentor, la langue de génération dépend de ce que tu écrit dans tes fichiers. Je pense que certains trucs sont en anglais (comme la navigation dans la documentation).

[Baldurien]

Je n'aime plus trop phpDoc.

Pour l'avoir utiliser, je le trouvais sympa au départ, mais assez vite j'ai du m'arrêter de l'utiliser.

D'une part, il n'a pas l'air vraiment bien codé (pour preuve, le tas de notice et warning qu'on trouve dans la ligne de commande quand on a réussi à la faire fonctionner)

D'autre part, le côté ligne de commande assez sporadique et le côté "t'utilises pas PEAR? ben t'as pas phpDoc".

J'ai abandonné phpDoc à la sortie de la 1.3 finale simplement à cause de ça, c'est débile car la doc générée est sympa - malgré que <code> ne fait pas ce qu'il devrait faire (ie: du code en ligne).

Je vais réessayer car, peut-être que le fait d'avoir plusieurs versions n'était pas trop apprécié, mais quand même ...

Quant à Doxygen : sympa dommage que php soit mal supporté :/

[edit] alternativement, il faut savoir que php5 avec l'API de réflection permet de chopper les phpdocs des méthodes, fonctions, et propriétés (ça ne fait pas les constantes, dommage).

[edit] oui donc, après avoir retenté, c'est toujours aussi merdique. la version 1.3 finale refuse carrément de démarrer en ligne de commande sans compter le basar pseudo shell et la jolie erreur du tout début (require_once failed, etc).

Autant la 1.3RC6 fonctionnait, autant là...

[Nonothehobbit]

Faut penser à ceux qui n'aurotn pas le courage comme toi d'aller farfouiller dans le code. Je suis d'accord qu'on en apprend plus en allant dans le code, mais tout le monde n'éprouve pas l'envie ou le besoin de savoir vraiment comment ça se passe la dessous.

[cedricgirard]

Si t'es tout seul sur ton projet et que t'arrives à totu avoir dans la tête ok, mais quand tu travailles à plusieurs

Non, je parle certes d'un projet perso mais aussi d'un projet en entreprise, où je ne suis pas seul sur le code.

la doc est quasiment indispensable car elle permet d'avoir rapidement les infos sur une classe/fonction/variable.

Elle permet d'avoir rapidement l'info à la condition qu'elle soit
- à jour (automatisation c ok, ça aide)
- renseignée, que les devs aient commentés correctement, et quand je vois le nombre de questions sur tel commentaire qui n'a pas été capté par le documentateur, je me dis que la route est longue
- cohérente avec le code, c'est à dire que les commentaires doivent être mis à jour en meme temps que le code

Les deux dernieres conditions me semblent une utopie dans un projet qui dure un peu.

Quand aux noms de fonctions qui s'autocommente c'est une utopie, on a souvent besoin de précision sur la gestion de cas particulier par exemple.
De plus avec php on indique pas le type des paramètres que l'on veux utiliser, seuls les commentaires et donc la doc permettent de le savoir...

Ben justement, si tu t'interesse à la méthode Extreme programming, des gens tres serieux et travaillant dans l'industrie (Chrysler pour les initiateurs principaux) soutiennent qu'un code qui a besoin d'un commentaire est un code qui a besoin d'être clarifié. Pour les types d'un langage non typé comme PHP, les noms de variables doivent être significatifs.

Tu imagines toi aller dans le code source de php pour savoir comment marche une fonction ???? Moi je dis vive la doc.

J'ai déjà admis que dans le cas d'un framework la doc est utile. Je repete que je parle pour un projet donc le but est de fabriquer un outil, pas d'un projet dont le but est de fournir une lib