Создание документации JavaScript с помощью Doxygen - PullRequest
Новая
       5

Создание документации JavaScript с помощью Doxygen

18 голосов
/ 06 сентября 2011

Я использую PHP и JavaScript в своем проекте, который полностью кодирую с помощью NetBeans 7.0.1. Мне очень нравится, как netbeans включает и использует стиль комментариев JavaDoc, как для PHP, так и для кода JS.

Теперь я хочу сгенерировать документацию по коду как из PHP, так и из кода JS. Я знаю, что есть несколько способов сделать это, но моя главная цель - иметь документацию для обеих частей в одной документации.

Чтобы объяснить это далее: Так, например, я мог бы использовать Doxygen и обрабатывать файлы PHP и JsDoc для обработки файлов JS. В результате у меня теперь есть два разных документа в двух разных папках - результат, который мне не нравится. Как я уже упоминал, я хочу оба в одной документации.

Итак, сначала я прошел путь с помощью помощника doxygen js2doxy.pl (http://jsunit.berlios.de/internal.html),, но он не был достаточно гибким. Он хорошо работает с «обычными» определенными функциями, но не с анонимными функциями js.

После долгих попыток я подумал, почему бы не изменить опцию FILE_PATTERNS документа для обработки файлов .js, поскольку стиль комментариев JavaDoc почти идентичен тому, который используется в PHP. И что ж, результат выглядит многообещающе, , но некоторые функции отсутствуют в документе.

Вот примеры: 

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

Это работает очень хорошо, я вижу документацию. Но: 

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

В этом примере я вижу документы для Language.Definitions, но не для replaceStrings (). У вас есть идеи, что я делаю не так? Та же самая конструкция очень хорошо обрабатывается JsDoc.

Также (часть Language.Definitions) ... 

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

... не отображается в документации.

Я также не возражаю, если кто-нибудь покажет мне, как лучше объединить два выхода doxygen и JsDoc в одну документацию.

Заранее большое спасибо!

Привет!

1 Ответ

10 голосов
/ 22 февраля 2012

См. Специальную команду \ fn , чтобы явно объявить функцию в doxygen, предпочтительно в заголовке источника, например: 

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