Generowanie dokumentacji JavaScript za pomocą Doxygen

Question

Używam PHP i JavaScript w moim projekcie, który całkowicie zakodowałem za pomocą netbeans 7.0.1. Bardzo podoba mi się to, jak Netbeans zawiera i używa stylu komentowania JavaDoc, zarówno dla PHP jak i kodu JS.

Teraz chcę wygenerować dokumentację kodu z PHP, a także z kodu JS. Wiem, że jest na to kilka sposobów, ale moim głównym celem jest posiadanie dokumentacji dla obu części w jednej dokumentacji.

Aby wyjaśnić to dalej: Więc np. Mógłbym użyć Doxygen i przetworzyć pliki PHP i JsDoc, aby przetworzyć pliki JS. W rezultacie mam teraz dwa różne dokumenty w dwóch różnych folderach - wynik, którego nie lubię. Jak już wspomniałem, chcę obie w jednej dokumentacji.

Tak więc najpierw przeszedłem drogę za pomocą doxygen helpera js2doxy.pl (http://jsunit.berlios.de/internal.html), ale to nie było wystarczająco elastyczne. Działa dobrze z "normalnymi" zdefiniowanymi funkcjami, ale nie z anonimowymi funkcjami js.

Po odrobinie wysiłku pomyślałem, dlaczego nie zmienić opcji FILE_PATTERNS dokumentu do przetwarzania plików .js, ponieważ styl JavaDoc komentarzy jest prawie identyczny z tymi używanymi w PHP. I dobrze, wynik wygląda obiecująco, ale niektóre funkcje brakuje w dokumencie.

Oto przykłady:

/** 
* Definitions for the languages. 
* @memberof Language 
*/ 
Language.Definitions = (function() 
{ 
... 
} 

To działa bardzo dobrze, mogę zapoznać się z dokumentacją. Ale:

** 
* Definitions for the languages 
* @memberof Language 
*/ 
Language.Definitions = (function() 
{ 
    var Translations = {}; 

    /** 
    * Replaces strings. 
    * @memberof Language 
    * @param string translation Translation string 
    * @param array parameters (optional) List of parameters 
    * 
    * @return string replaced string 
    */ 
    function replaceStrings(translation, parameters) 
    { 
     ... 
    } 

W tym przykładzie widzę dokumenty dla Language.Definitions, ale nie dla replaceStrings(). Czy masz jakiś pomysł, co robię źle? Ten sam konstrukt jest procesem JsDoc bardzo dobrze.

także (część Language.Definitions) ...

... 
return { 
     /** 
     * Initialize translations 
     * 
     * @memberof Language 
     */ 
     initTranslations: function() 
     { 
      ... 
     } 
... 
} 

... nie jest pokazany w dokumentacji.

Ja też nie miałbym nic przeciwko, gdyby ktoś pokazał mi jak najlepiej połączyć dwa wyjścia doxygen i JsDoc w jedną dokumentację.

Bardzo dziękuję z góry!

Pozdrowienia!

Answer 1

Zobacz specjalną komendę \fn jawnie zadeklarować funkcję w doxygen, najlepiej w nagłówku źródła, tak:

/*! 
* Language 
* Declare the root class 
* \Class Language 
*/ 

/*! 
* definitions is a property in the Language class 
* \property Definitions definitions 
*/ 

/*! 
* Document the Definitions static class that used as property in the Language class 
* \Class Definitions 
*/ 

/*! 
* Replaces strings 
* Document the static method for the Definitions class 
* \fn string replaceStrings(translation, parameters) 
* \memberof Definitions 
* \param string translation Translation string 
* \param array parameters (optional) List of parameters 
* \return string replaced string 
*/ 

Language.definitions = (function() 
{ 
    var Translations = {}; 

    function replaceStrings(translation, parameters) 
    { 
     ... 
    }