javascript - smart - programar contratos inteligentes

Generar documentación de JavaScript con Doxygen.

Question

Utilizo PHP y JavaScript en mi proyecto, que codifico completamente con netbeans 7.0.1. Realmente me gusta cómo netbeans incluye y usa el estilo de comentarios JavaDoc, tanto para PHP como para código JS.

Ahora, quiero generar la documentación del código desde PHP, así como el código JS. Sé que hay varias maneras de hacerlo, pero mi objetivo principal es tener la documentación de ambas partes en una documentación.

Para explicarlo más: Así, por ejemplo, podría usar Doxygen y procesar los archivos PHP y JsDoc para procesar los archivos JS. El resultado sería que ahora tengo dos documentos diferentes en dos carpetas diferentes, un resultado que no me gusta. Como mencioné, quiero ambos en una documentación.

Entonces, primero seguí el camino utilizando el ayudante de doxygen js2doxy.pl (http://jsunit.berlios.de/internal.html), pero eso no era lo suficientemente flexible. Funciona bien con funciones definidas "normales", pero no con funciones js anónimas.

Después de un poco de intentarlo, pensé por qué no alterar la opción FILE_PATTERNS del documento para procesar archivos .js, ya que el estilo JavaDoc de los comentarios es casi idéntico a los utilizados con PHP. Y bueno, el resultado parece prometedor, pero faltan algunas funciones en el documento.

Aquí hay algunos ejemplos:

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

Esto funciona muy bien, puedo ver la documentación. Pero:

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

En este ejemplo, veo los documentos para Language.Definitions pero no para replaceStrings (). ¿Tienes alguna idea de lo que estoy haciendo mal? El mismo constructo es procesado muy bien por JsDoc.

También (parte de Language.Definitions) ...

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

... no se muestra en la documentación.

Tampoco me importaría si alguien me mostrara la mejor manera de combinar las dos salidas de doxygen y JsDoc en una documentación.

¡Muchas gracias por adelantado!

¡Saludos!

Answer 1

Vea el comando especial /fn para declarar explícitamente la función en el doxygen, preferiblemente en el encabezado de la fuente, así:

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