web-dev-qa-db-fra.com

Comment documentez-vous vos PHP fonctions et classes en ligne?

Je sais qu'il existe de nombreuses normes différentes pour la documentation en ligne PHP code. Voici ce que j'entends par documentation en ligne, et veuillez me corriger s'il existe un meilleur terme:

/**
* This is the description for the class below.
*
* @package    my-package
* @subpackage my-subpackage
* @author     my-name
* @version    my-version
* ...
*/
class orderActions {
...

Quelle est la forme de documentation en ligne la meilleure et la plus largement acceptée? En d'autres termes, quelles sont ces formes de documentation en ligne sur lesquelles tout le monde est d'accord et qui ne reposent pas de manière significative sur des opinions; les formes universellement acceptées de PHP documentation en ligne que tout le monde devrait connaître, mais en tant que questionneur, je ne suis pas encore sûr, mais après avoir répondu à cette question, j'aurai une bonne aperçu de, n'impliquant aucune opinion particulière.

Existe-t-il des outils pour générer automatiquement une telle documentation, ou doit-il être fait à la main?

Je ne suis pas intéressé par la génération de manuels - je veux savoir comment générer le type de code commenté ci-dessus, ou "documentation en ligne".

phpdocumentationcomments
34
James Skidmore

PHPDoc , comme ce que vous avez publié, est une forme largement acceptée de documentation PHP.

Vous pouvez utiliser Doxygen pour générer automatiquement les documents.

Edit: En termes de génération de documentation en ligne dans votre code, je n'ai jamais rencontré d'outil qui reviendra en arrière et le fera en externe pour un projet. Il est généralement laissé dans le domaine du IDE pour générer un modèle pendant que vous codez.

Eclipse fait en fait un travail décent (c'est l'une des rares choses que j'aime chez Eclipse) et je pense que Netbeans le fait aussi. Tous les principaux IDE auront probablement des fonctionnalités pour aider à ce type de génération de modèle.

43
zombat

Choisissez parmi:

Voir aussi article Wikipedia, "Comparaison des générateurs de documentation", section "par langue" .

8
Benoit Blanchon

J'ai créé un documentateur très simple à utiliser et compatible avec phpdoc:

Exemple:

<?php
    $docs = new QuickDocumenter();
    $docs->parseString("
    /**
    *   Sanitize string
    *
    *   @since      1.0
    *   @version    1.0
    */
    ");
    foreach( $docs->result() as $doc)
    {
        highlight_string( print_r( $doc , true ) );
        echo "<hr/>";
    }
?>

Voir dans Github:

https://github.com/olaferlandsen/QuickDocumenter

1
Jorge Olaf Erlandsen

Habituellement, vous écriviez vous-même les commentaires du docblock, bien que je suppose que certains IDE peuvent créer un modèle pour vous.

J'ai fait écrire un programme, qui peut tracer un programme en cours d'exécution et détecter les types de paramètres et les réécrire en tant que commentaires docblock . C'est un peu bogué, mais ça marche.

1
troelskn

Bien que je ne l'ait pas complètement utilisé, Doxygen semble prometteur pour cette tâche.

Si vous connaissez l'outil JavaDoc pour Java, il est assez similaire à cela. Vous utilisez le style Doxygen, puis exécutez l'outil sur vos fichiers source pour produire de la documentation.

0
Thomas Owens

Je ne sais pas exactement ce que vous codez, mais j'ai plusieurs extraits (j'utilise Textmate) que j'ajoute juste pendant que je travaille) .J'ai trouvé que cela aboutit aux meilleurs résultats car je remplis les détails au lieu de faire confiance à un système pour le faire pour moi.

C'est plus de travail au début mais ça en vaut la peine à long terme

0
Jason