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

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语法，这样解析器就不会出错。但这也意味着我要修改原始文件的代码，而我希望避免这种情况（我更喜欢仅添加文档注释）。

谢谢！

- mathematical.coffee

---

你找到了解决方法吗？ - Shailesh Tainwala

你能否更改管道，使得在压缩等操作之前，jsdoc在中间编译版本上运行？如果不行，那么一种较少侵入性的代码hack是const HAVE_BLUETOOTH = +'@HAVE_BLUETHOOTH@'; - lemonzi

Answer 1

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

所以，我通过使用JSDoc插件commentsOnly解决了我的问题（使用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

它可以工作！没有理由它不能与您的文件一起使用。

希望我能帮到您；）

- Bruno J. S. Lesieur