Question

我正在尝试使用JSDoc（3）来记录Javascript文件，如下所示：

/** 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忽略此文件中的所有代码，只需考虑注释？（我可能需要为每个doclet添加@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语法，以便解析器不会抱怨，但这也意味着我正在修改我想避免的原始文件的代码（我更喜欢只是< / em>添加文档）。

欢呼声

Answer 1

我的情况类似，因为我使用JSDoc来评论我的.less和.css文件。当我在文件集上运行JSDoc时，我遇到了同样的问题。

所以，我使用commentsOnly JSDoc插件解决了我的问题（使用JSDoc 3.3.3）

https://github.com/jsdoc3/jsdoc/blob/master/plugins/commentsOnly.js

我创建了这个config.json：

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

将commentsOnly.js文件放入plugin/目录（考虑plugin/和config.json在同一文件夹中）并在此文件夹中执行以下CLI命令：

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

它的工作！没有理由不对您的文件起作用。

希望我帮助你;）

JSDoc - 标记一些代码不被解析但保留文档？

1 个答案: