W jaki sposób dokumentujesz swoje funkcje PHP i klasy w linii?

Question

Wiem, że istnieje wiele różnych standardów dla wbudowanej dokumentacji kodu PHP. Oto co mam na myśli dokumentacji inline, i proszę mnie poprawić, jeśli istnieje lepszy termin:

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

Jaki jest najlepszy i najbardziej powszechnie akceptowaną formą dokumentacji inline? Czy są jakieś narzędzia do automatycznego generowania takiej dokumentacji, czy też trzeba to zrobić ręcznie?

Nie jestem zainteresowany generowaniem instrukcji obsługi - chcę się dowiedzieć, jak wygenerować typ kodu, który został opisany powyżej, lub "dokumentacja wbudowana".

Answer 1

PHPDoc, podobnie jak to, co napisałeś, jest powszechnie akceptowaną formą dokumentacji PHP.

Możesz użyć Doxygen, aby automatycznie wygenerować dokumenty.

Edycja: Jeśli chodzi o generowanie dokumentacji in-line w kodzie, nigdy nie natknąłem się na narzędzie, które powróci i zrobi to zewnętrznie dla projektu. W kodzie IDE generalnie jest generowany szablon podczas kodowania.

Eclipse rzeczywiście wykonuje dobrą robotę (jest to jedna z niewielu rzeczy, które lubię w Eclipse) i wierzę, że Netbeans również to robi. Każdy znaczący IDE będzie prawdopodobnie miał funkcjonalność wspomagającą generowanie tego typu szablonów.

Answer 2

Chociaż nie w pełni go wykorzystałem, Doxygen wygląda obiecująco na to zadanie.

Jeśli znasz narzędzie JavaDoc dla języka Java, jest ono bardzo podobne. Używasz stylu Doxygen, a następnie uruchamiasz narzędzie nad plikami źródłowymi, aby utworzyć dokumentację.

Answer 3

Zazwyczaj pisałbyś do siebie komentarze do dokumentu, chociaż przypuszczam, że niektóre IDE mogą stworzyć dla ciebie szablon.

Zrobiłem tak naprawdę write a program, which can trace a running program and detect parameter types and write them back as docblock comments. Jest trochę błędny, ale to rodzaj pracy.

Answer 4

Nie jestem pewien, co kodujesz, ale mam kilka fragmentów (używam Textmate), które dodajemy po prostu, gdy pracuję). Stwierdziłem, że to kończy się najlepszymi wynikami, odkąd uzupełniam szczegóły zamiast ufać systemowi, który to zrobi dla mnie.

Jest więcej pracy na początku, ale wydaje się, że warto na dłuższą metę

Answer 5

i stworzył documentator bardzo prosty w obsłudze i kompatybilny z PHPDoc:

Przykład:

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

Zobacz w Github:

https://github.com/olaferlandsen/QuickDocumenter

Pa!

Answer 6

Wybierz z:

• Doxygen
• phpDocumentator
• Sami
• ApiGen
• CakePHP API docs
• phpDox

Zobacz także Wikipedia article, "Comparison of documentation generators", section "by Language".