Genera documentazione JavaScript con Doxygen

Question

Io uso PHP e JavaScript nel mio progetto, che codifico interamente con netbeans 7.0.1. Mi piace molto come netbeans include e usa lo stile di commento JavaDoc, sia per il codice PHP che per quello JS.

Ora, voglio generare la documentazione del codice da PHP e dal codice JS. So che ci sono diversi modi per farlo, ma il mio obiettivo principale è quello di avere la documentazione per entrambe le parti nella documentazione una.

Per spiegarlo meglio: ad esempio, potrei utilizzare Doxygen ed elaborare i file PHP e JsDoc per elaborare i file JS. Il risultato sarebbe che ora ho due documenti diversi in due cartelle diverse, un risultato che non mi piace. Come ho detto, voglio entrambi in una documentazione.

Quindi, per prima cosa ho utilizzato l'helper doxygen js2doxy.pl (http://jsunit.berlios.de/internal.html), ma non era abbastanza flessibile. Funziona bene con funzioni definite "normali", ma non con funzioni js anonime.

Dopo un po 'di tentativi ho pensato perché non modificare l'opzione FILE_PATTERNS del documento per elaborare i file .js, poiché lo stile JavaDoc dei commenti è quasi identico a quello utilizzato con PHP. E bene, il risultato sembra promettente, ma alcune funzioni mancano nel doc.

Ecco alcuni esempi:

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

Questo funziona molto bene, posso vedere la documentazione. Ma:

** 
* 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) 
    { 
     ... 
    } 

In questo esempio vedo i documenti per Language.Definitions ma non per replaceStrings(). Hai qualche idea, cosa sto facendo male? Lo stesso costrutto è trattato molto bene da JsDoc.

anche (parte di Language.Definitions) ...

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

... non è indicata nella documentazione.

Inoltre, non mi dispiacerebbe se qualcuno mi mostrasse come combinare al meglio le due uscite di doxygen e JsDoc in un'unica documentazione.

Grazie mille in anticipo!

Saluti!

Answer 1

vedere il comando speciale \fn dichiarare esplicitamente la funzione nel Doxygen, preferibilmente nell'intestazione della fonte, in questo modo:

/*! 
* 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) 
    { 
     ... 
    }