Que pensez-vous des générateurs de doc PHP ?

[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]

Envoyé par Nonothehobbit

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 :

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

et

Code :

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]

Envoyé par Nonothehobbit

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]

Envoyé par cedricgirard

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]

Envoyé par cedricgirard

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]

Envoyé par 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")

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.

[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]

Envoyé par 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

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

Envoyé par Nonothehobbit

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.

Envoyé par Nonothehobbit

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.

Envoyé par Nonothehobbit

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

[Curtis]

Envoyé par 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?

On peut voir ca comme ca. Il est sur qu'un projet de 50 ligne
n'a pas besoin de générateur de code. Mais pour les gros projets,
il est bien plus clair d'avoir une documentation automatique.
De plus lorsque des nouveaux développpeurs arrivent dessus
il est plus simple pour lui de parcourir la documentation automatique
et de se faire une idée des outils (bibliothèque) qu'il a à disposition
que de lui infliger une lecture de 5 milliard de lignes de codes ...

Envoyé par cedricgirard

Un code clair et propre a t'il besoin de documentation de code?

Oui, mille fois oui. Meme si tu as généré un code nickel chrome,
le développeur se fou que pour la fonction ListeIMMO par exemple,
derrière se cache 12 objets et 15 fonctions. Lui il connait ce que lui
retourne la fonction et ce qu'il doit lui donner à manger. Si tu
n'a pas de générateur de code, le pauvre gars se tape tout le code
pour savoir ce que fait la fonction.

Envoyé par cedricgirard

D'une documentatiion d'architecture OK, mais de documentation du code?

Et puis le problème sous jacent et bien réel des documentation qui
ne sont pas dynamiques, c'est qu'elles ne sont jamais à jour ....

Envoyé par cedricgirard

D'
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.

Malheureusement tous les développeurs qui travaillent sur des projets
ne sont pas systématiquement des développeurs comme on en rêve tous
et du coup la génération de docuementation automatique OBLIGE à une
certaine rigueur de commentaires, c'est pas plus mal non ??

Envoyé par cedricgirard

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)

[/quote]


Et tu n'as jamais utilisé de générateur de code, ben dis donc j'ai hate
d'avoir tes premiers sentiment sur ce genre d'outil.
Personnelement je ne l'utilise que depuis 1 an et je trouve ca franchement
pratique

[Nonothehobbit]

Ah c'est comme tout, faut pas critiquer avant d'avoir essayé, on a souvent des surprises.

[cedricgirard]

Envoyé par 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.

Pour une lib externe, je suis d'accord que ce n'est pas souvent utile (quoique) mais je parle là du projet sur lequel le developpeur dont on parle travaille : s'il n'est pas capable de se lancer dans le code de SON projet, il n'a rien à apporter à ce projet.