JSDoc - пометить какой-либо код, чтобы он не анализировался, но сохранить документацию?

Я пытаюсь задокументировать файл Javascript с помощью JSDoc (3) следующим образом:

/** 1 if gnome-bluetooth is available, 0 otherwise                              
 * @type {boolean}                                                              
 * @const                                                                                                                                           
 */                                                                             
const HAVE_BLUETOOTH = @HAVE_BLUETOOTH@;

Теперь файл (названный config.js.in) не является действительным Javascript; файл запускается через Makefile, который заменяет подходящее значение для @HAVE_BLUETOOTH@.

Когда я пытаюсь запустить JSdoc на этом, он (по понятным причинам) отказывается из-за синтаксической ошибки в файле.

Есть ли способ заставить JSDoc игнорировать весь код в этом файле, а просто учитывать аннотации? (Возможно, мне придется добавить теги @name к каждому доклету, чтобы полностью отделить документацию от кода; это нормально).

Что-то типа:

/** 1 if gnome-bluetooth is available, 0 otherwise                              
 * @name HAVE_BLUETOOTH
 * @type {boolean}                                                              
 * @const                                                                 
 */                    
/** @ignore */  // somehow ignore from here onwards
const HAVE_BLUETOOTH = @HAVE_BLUETOOTH@; 
/** !@ignore */ // somehow don't ignore from here onwards (although I'd be happy
                // to ignore the entire file)

Я бы предпочел не изменять кодовую часть файла, если это возможно (я добавляю документацию в существующий проект). Например, я, вероятно, мог бы обойти это с помощью

const HAVE_BLUETOOTH = parseInt('@HAVE_BLUETOOTH@', 10);

что сделало бы файл снова верным синтаксисом JS, чтобы синтаксический анализатор не жаловался, но это также означает, что я изменяю код исходного файла, которого я хочу избежать (я предпочитаю просто добавить документацию).

ваше здоровье


jsdoc
person mathematical.coffee    schedule 15.10.2012    source источник
comment
Вы нашли обходной путь?   -  person Shailesh Tainwala    schedule 14.08.2014
comment
Не можете ли вы изменить конвейер, чтобы jsdoc запускался в промежуточной, скомпилированной версии, прежде чем вы минимизируете и т. д.? Если нет, то можно использовать менее навязчивый хак const HAVE_BLUETOOTH = +'@HAVE_BLUETHOOTH@';   -  person lemonzi    schedule 06.06.2015

Ответы (1)


arrow_upward
0
arrow_downward

Мой случай аналогичен, потому что я использую JSDoc для комментирования файлов .less и .css. Когда я запускаю JSDoc для набора файлов, у меня возникает та же проблема.

Итак, я решаю свою проблему (с JSDoc 3.3.3) с помощью плагина commentsOnly JSDoc.

Я создал это config.json:

{
    "source": {
        "includePattern": ".+\\.(css|less)?$"
    },
    "plugins": [
        "plugin/commentsOnly"
    ]
}

с файлом commentsOnly.js в каталог plugin/ (учитывайте, что plugin/ и config.json находятся в одной папке), и в этой папке я выполняю следующую команду CLI:

jsdoc -c ./config.json ./assets/stylesheets/common.less

И это работа! Нет никаких причин, по которым это не работает с вашими файлами.

Надеюсь я вам помог ;)

person Bruno J. S. Lesieur    schedule 04.12.2015