IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)
Navigation

Inscrivez-vous gratuitement
pour pouvoir participer, suivre les réponses en temps réel, voter pour les messages, poser vos propres questions et recevoir la newsletter

EDI, CMS, Outils, Scripts et API PHP Discussion :

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


Sujet :

EDI, CMS, Outils, Scripts et API PHP

  1. #1
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut Que pensez-vous des générateurs de doc PHP ?

    === 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...

  2. #2
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut
    Définitivement : www.phpdoc.org/

    Ce prog est une tuerie ! J'adore.

  3. #3
    Nouveau membre du Club
    Inscrit en
    Janvier 2003
    Messages
    38
    Détails du profil
    Informations forums :
    Inscription : Janvier 2003
    Messages : 38
    Points : 27
    Points
    27
    Par défaut
    Citation 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 : 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 ;-)
    Magaly

    Venez visiter mon site si vous appréciez la chanteuse et actrice Elsa Lunghini
    NOUVEL ALBUM "De lave et de sève" : sortie le 27 avril!

  4. #4
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut
    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...

  5. #5
    Nouveau membre du Club
    Inscrit en
    Janvier 2003
    Messages
    38
    Détails du profil
    Informations forums :
    Inscription : Janvier 2003
    Messages : 38
    Points : 27
    Points
    27
    Par défaut
    Citation 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?
    Magaly

    Venez visiter mon site si vous appréciez la chanteuse et actrice Elsa Lunghini
    NOUVEL ALBUM "De lave et de sève" : sortie le 27 avril!

  6. #6
    Nouveau membre du Club
    Inscrit en
    Janvier 2003
    Messages
    38
    Détails du profil
    Informations forums :
    Inscription : Janvier 2003
    Messages : 38
    Points : 27
    Points
    27
    Par défaut
    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...
    Magaly

    Venez visiter mon site si vous appréciez la chanteuse et actrice Elsa Lunghini
    NOUVEL ALBUM "De lave et de sève" : sortie le 27 avril!

  7. #7
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut
    Oui : j'ai testé en copiant/collant ton commentaire sur une méthode d'une classe bidon et tout passe bien.

  8. #8
    Membre averti
    Homme Profil pro
    Développeur Web
    Inscrit en
    Mai 2002
    Messages
    299
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Développeur Web
    Secteur : Santé

    Informations forums :
    Inscription : Mai 2002
    Messages : 299
    Points : 373
    Points
    373
    Par défaut
    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

  9. #9
    Nouveau membre du Club
    Inscrit en
    Janvier 2003
    Messages
    38
    Détails du profil
    Informations forums :
    Inscription : Janvier 2003
    Messages : 38
    Points : 27
    Points
    27
    Par défaut
    Citation 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...
    Magaly

    Venez visiter mon site si vous appréciez la chanteuse et actrice Elsa Lunghini
    NOUVEL ALBUM "De lave et de sève" : sortie le 27 avril!

  10. #10
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut
    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.

  11. #11
    Futur Membre du Club
    Inscrit en
    Janvier 2004
    Messages
    5
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 5
    Points : 6
    Points
    6
    Par défaut
    Citation 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 .

  12. #12
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut
    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")

  13. #13
    Membre averti
    Homme Profil pro
    Développeur Web
    Inscrit en
    Mai 2002
    Messages
    299
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Développeur Web
    Secteur : Santé

    Informations forums :
    Inscription : Mai 2002
    Messages : 299
    Points : 373
    Points
    373
    Par défaut
    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)

  14. #14
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut
    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.

  15. #15
    Membre averti
    Homme Profil pro
    Développeur Web
    Inscrit en
    Mai 2002
    Messages
    299
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Développeur Web
    Secteur : Santé

    Informations forums :
    Inscription : Mai 2002
    Messages : 299
    Points : 373
    Points
    373
    Par défaut
    Citation 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.

  16. #16
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut
    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.

  17. #17
    Membre averti
    Homme Profil pro
    Développeur Web
    Inscrit en
    Mai 2002
    Messages
    299
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Développeur Web
    Secteur : Santé

    Informations forums :
    Inscription : Mai 2002
    Messages : 299
    Points : 373
    Points
    373
    Par défaut
    Citation 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.
    Citation 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.

    Citation 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.

    Citation 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

  18. #18
    Futur Membre du Club
    Inscrit en
    Janvier 2004
    Messages
    5
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 5
    Points : 6
    Points
    6
    Par défaut
    Citation 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 ...

    Citation 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.

    Citation 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 ....



    Citation 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 ??

    Citation 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

  19. #19
    Membre à l'essai

    Inscrit en
    Janvier 2004
    Messages
    25
    Détails du profil
    Informations forums :
    Inscription : Janvier 2004
    Messages : 25
    Points : 21
    Points
    21
    Par défaut
    Ah c'est comme tout, faut pas critiquer avant d'avoir essayé, on a souvent des surprises.

  20. #20
    Membre averti
    Homme Profil pro
    Développeur Web
    Inscrit en
    Mai 2002
    Messages
    299
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Développeur Web
    Secteur : Santé

    Informations forums :
    Inscription : Mai 2002
    Messages : 299
    Points : 373
    Points
    373
    Par défaut
    Citation 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.

Discussions similaires

  1. [Internals] Que pensez-vous des Fermetures en PHP ?
    Par Yogui dans le forum Langage
    Réponses: 22
    Dernier message: 14/02/2010, 07h49
  2. [Sondage] Que pensez-vous des enfants de Don Quichotte?
    Par Aitone dans le forum Politique
    Réponses: 16
    Dernier message: 24/01/2007, 10h33
  3. [Architecture][Stratégie] Que pensez-vous des applications Java online ?
    Par Francoisvandenbergh dans le forum Général Java
    Réponses: 19
    Dernier message: 24/02/2006, 16h49
  4. [Choix] Que pensez vous des CMS de type Mambo ?
    Par Nikeleos dans le forum EDI, CMS, Outils, Scripts et API
    Réponses: 5
    Dernier message: 02/09/2005, 13h45
  5. [Débat] Que pensez-vous des langages à typage dynamique?
    Par Eusebius dans le forum Langages de programmation
    Réponses: 14
    Dernier message: 16/06/2004, 13h12

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo