Comment décrivez-vous votre PHP des fonctions et des classes inline?

Je sais qu'il y a beaucoup de normes différentes pour PHP code en ligne de la documentation. Voici ce que je veux dire par inline de la documentation, et s'il vous plaît corrigez-moi si il y a une meilleure durée:

/**
* 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 meilleure et la plus largement acceptée formulaire en ligne de la documentation? En d'autres termes, quelles sont ces formes en ligne de la documentation que tout le monde est d'accord sur, et ne sont pas significativement sur la base des avis; universellement accepté formes de PHP en ligne de la documentation que chacun devrait le savoir, mais comme un interlocuteur, je ne suis pas sûr encore, mais après répondre à cette question, je vais avoir un bon aperçu de n'impliquant pas tout particulier opinions.

Existe-il des outils de génération automatique des documents, ou doit-il être fait à la main?

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

  • Qu'entendez-vous par votre la dernière modification? Je ne comprends pas ce que tu veux dire par "comment générer ce inline documentation".
  • Désolé, pour clarifier les choses: je me demande comment générer le type de code les commentaires (ou "inline " documentation") dans l'exemple.
InformationsquelleAutor James Skidmore | 2009-07-25
  1. 43

    PHPDoc, à l'instar de ce que vous avez posté, est largement accepté forme de documentation de PHP.

    Vous pouvez utiliser Doxygen à auto-produire de la documentation.

    Edit: En terme de génération de documentation en ligne dans votre code, je n'ai jamais rencontré un outil qui permettra de revenir en arrière et le faire de l'extérieur pour un projet. Il est généralement laissé dans le domaine de l'IDE pour générer un modèle tout en vous code.

    Eclipse est en fait un travail décent de cela (il est l'une des rares choses que j'aime à propos de l'Éclipse) et je crois que Netbeans ne ainsi. Majeur de développement va probablement avoir des fonctionnalités pour aider avec ce type de génération de modèle.

    • PHPDocumentor est probablement le plus commun et il est recommandé d'ajouter de la documentation de l'API.
    • Est-il possible de générer inline documentation avec PHPDoc si? Je pensais que c'était seulement pour la génération de la documentation les manuels.
    • +1 Fonctionne vraiment bien et s'intègre avec netbeans.
    • Je voulais faire une distinction: PHPDoc est une syntaxe pour les commentaires (adapté de JavaDoc) en.wikipedia.org/wiki/PHPDoc. PHPDocumentor est un des outils capables de lire ces commentaires et de produire de la documentation utilisable pages/XML. Il est également Doxygen, et probablement d'autres.
    • C'est une bonne clarification à faire, merci. Mon lien est allé à PHPDocumentor comme je l'utiliser comme une référence pour PHPDoc la syntaxe, mais en général, je utiliser Doxygen pour la génération. Je vais ajuster le lien pour accéder à la syntaxe de référence à la place.
    • Doxygen est génial.
    • Dans vim, vous pouvez utiliser snipMate pour créer de la fonction et des classes ainsi que de la documentation.

    InformationsquelleAutor zombat
  3. 1

    Habituellement, vous devez écrire le docblock commentaires de votre auto, bien que je suppose que certains IDE pouvez créer un modèle pour vous.

    Je n'ai fait écrire un programme, qui peut tracer l'exécution d'un programme et de détecter les types de paramètres et de les écrire à l'arrière comme docblock commentaires. C'est un peu buggé, mais ce genre de travaux.

    InformationsquelleAutor troelskn
  4. 1

    J'ai créé un documentator qui est 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 sur Github:

    https://github.com/olaferlandsen/QuickDocumenter

    • L'orthographe de @ matures devrait être @depuis :')
    InformationsquelleAutor Olaf Erlandsen
  5. 0

    Vous ne savez pas quoi code mais j'ai plusieurs fragments de code (j'utilise Textmate) que je viens de l'ajouter en tant que je suis en train de travailler), j'ai trouvé cela se termine avec les meilleurs résultats depuis que je suis en remplissant 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 il semble être à la peine dans le long terme

    InformationsquelleAutor Jason
  6. 0

    Bien que je n'ai pas utilisé pleinement il, Doxygen semble prometteur pour cette tâche.

    Si vous êtes familier avec l'outil JavaDoc pour Java, c'est tout à fait semblable. Vous utilisez le Doxygen style, puis exécutez l'outil au-dessus de vos fichiers source pour produire de la documentation.

    InformationsquelleAutor Thomas Owens