Question

I use PHP and JavaScript in my project, which I entirely code with netbeans 7.0.1. I really like how netbeans includes and uses the JavaDoc commenting style, both for PHP and JS code.

Now, I want to generate the code documentation from PHP as well as JS code. I know there are several ways doing it, but my main aim is to have the documentation for both parts in one documentation.

To explain it further: So e.g., I could use Doxygen and process the PHP files and JsDoc to process the JS files. The result would be, that I now have two different docs in two different folders – a result which I don’t like. As I mentioned, I want both in one documentation.

So, first I went the way via using the doxygen helper js2doxy.pl (http://jsunit.berlios.de/internal.html), but that wasn’t flexible enough. It works well with “normal” defined functions, but not with anonymous js functions.

After a bit of trying a lot I thought why not alter the FILE_PATTERNS option of document to process .js files, as the JavaDoc style of the comments are nearly identical to the ones used with PHP. And well, the result looks promising, but some functions are missing in the doc.

Here are examples:

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

This works very well, I can see the documentation. But:

**
 * 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 this example I see the docs for Language.Definitions but not for replaceStrings(). Do you have any idea, what I am doing wrong? The same construct is process by JsDoc very well.

Also (part of Language.Definitions) …

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

… is not shown in the documentation.

I also wouldn’t mind if someone would show me how to best merge the two outputs of doxygen and JsDoc into one documentation.

Thanks a lot in advance!

Greetings!

Answer 1

See the special command \fn to explicitly declare the function in the doxygen, preferably in the header of source, like this:

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