Wie dokumentieren Sie Ihre PHP-Funktionen und -Klassen inline? [closed]

Ich weiß, dass es viele verschiedene Standards für die Inline-Dokumentation von PHP-Code gibt. Hier ist, was ich mit Inline-Dokumentation meine, und bitte korrigieren Sie mich, wenn es einen besseren Begriff gibt:

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

Was ist die beste und am weitesten verbreitete Form der Inline-Dokumentation? Mit anderen Worten, was sind diese Formen der Inline-Dokumentation, denen alle zustimmen und die nicht wesentlich auf Meinungen basieren? die allgemein akzeptierten Formen der PHP-Inline-Dokumentation, über die jeder Bescheid wissen sollte, aber als Fragesteller bin ich mir noch nicht sicher, aber nachdem diese Frage beantwortet ist, werde ich einen guten Überblick darüber haben, ohne irgendwelche bestimmten Meinungen einzubeziehen.

Gibt es Tools, um eine solche Dokumentation automatisch zu erstellen, oder muss dies von Hand erfolgen?

Ich bin nicht daran interessiert, Handbücher zu generieren – ich möchte wissen, wie man den oben kommentierten Codetyp oder „Inline-Dokumentation“ generiert.

PHPDocwie das, was Sie gepostet haben, ist eine weithin akzeptierte Form der PHP-Dokumentation.

Sie können verwenden Sauerstoff um die Dokumente automatisch zu generieren.

Bearbeiten: In Bezug auf die Generierung von Inline-Dokumentation in Ihrem Code bin ich noch nie auf ein Tool gestoßen, das zurückgeht und dies extern für ein Projekt tut. Es bleibt im Allgemeinen im Bereich der IDE, eine Vorlage zu generieren, während Sie codieren.

Eclipse macht das wirklich gut (das ist eines der wenigen Dinge, die ich an Eclipse mag) und ich glaube, Netbeans tut das auch. Jede größere IDE verfügt wahrscheinlich über Funktionen zur Unterstützung dieser Art der Vorlagengenerierung.

Wähle aus:

• Sauerstoff
• phpDocumentator
• Sami
• ApiGen
• CakePHP-API-Dokumentation
• phpDox

Siehe auch die Wikipedia-Artikel, „Vergleich von Dokumentationsgeneratoren“, Abschnitt „nach Sprache“.

Normalerweise würden Sie die Docblock-Kommentare selbst schreiben, obwohl ich annehme, dass einige IDEs eine Vorlage für Sie erstellen können.

Das habe ich tatsächlich Schreiben Sie ein Programm, das ein laufendes Programm verfolgen und Parametertypen erkennen und als Docblock-Kommentare zurückschreiben kann. Es ist ein bisschen buggy, aber es funktioniert irgendwie.

Ich habe einen Dokumentator erstellt, der sehr einfach zu bedienen und mit phpdoc kompatibel ist:

Beispiel:

<?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/>";
    }
?>

Siehe auf Github:

https://github.com/olaferlandsen/QuickDocumenter

Ich bin mir nicht sicher, was Sie codieren, aber ich habe mehrere Ausschnitte (ich verwende Textmate), die ich einfach während der Arbeit hinzufüge.) Ich habe festgestellt, dass dies zu den besten Ergebnissen führt, da ich die Details ausfülle, anstatt einem zu vertrauen System, es für mich zu tun.

Es ist am Anfang mehr Arbeit, aber es scheint sich auf lange Sicht zu lohnen

Obwohl ich es nicht vollständig genutzt habe, Sauerstoff sieht für diese Aufgabe vielversprechend aus.

Wenn Sie mit dem JavaDoc-Tool für Java vertraut sind, ist es dem ziemlich ähnlich. Sie verwenden den Doxygen-Stil und führen das Tool dann über Ihre Quelldateien aus, um eine Dokumentation zu erstellen.