JSDoc-将一些代码标记为不解析但保留文档? [英] JSDoc - mark some code to not be parsed but retain documentation?

问题描述

我正尝试使用JSDoc(3)来记录Javascript文件，如下所示:

I'm trying to document a Javascript file with JSDoc(3) like so:

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

现在该文件(称为config.js.in)不是使用其自身的有效Javascript了；该文件通过Makefile运行，该文件用@HAVE_BLUETOOTH@替代适当的值.

Now the file (called config.js.in) is not on its own valid Javascript; the file gets run through a Makefile which substitutes an appropriate value for @HAVE_BLUETOOTH@.

当我尝试对此运行JSdoc时，由于文件中的语法错误，它(可以理解)不受欢迎.

When I try to run JSdoc on this, it (understandably) balks because of the syntax error in the file.

是否可以通过某种方式告诉JSDoc忽略此文件中的所有代码，而只需考虑注释? (我可能必须在每个doclet中添加@name标记，以将文档与代码完全分开；没关系).

Is there some way to tell JSDoc to ignore all code in this file but simply take into account the annotations? (I might have to add @name tags to each doclet to completely separate the documentation from the code; that's fine).

类似的东西:

/** 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)

如果可能的话，我宁愿不要修改文件的代码部分(我将文档添加到现有项目中).例如，我可能可以通过

I'd prefer not to modify the code part of the file, if possible (I'm adding documentation to an existing project). For example, I could probably get around it with

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

这将使文件再次具有有效的JS语法，以便解析器不会抱怨，但这也意味着我正在修改要避免的原始文件的代码(我更喜欢 just 添加文档).

which would make the file have valid JS syntax again so that the parser doesn't complain, but this also means I'm modifying the code of the original file which I want to avoid (I prefer to just add documentation).

欢呼

推荐答案

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

My case is similar because I use JSDoc to comment my .less and .css file. When I running JSDoc on set of file, I have the same issue.

因此，我使用commentsOnly JSDoc插件解决了我的问题(使用JSDoc 3.3.3)

So, I resolve my problem (with JSDoc 3.3.3) with the commentsOnly JSDoc plugin

• 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命令:

with the commentsOnly.js file into a plugin/ directory (consider plugin/ and config.json are in same folder) and in this folder I execute the following CLI command:

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

就可以了！没有理由这不适用于您的文件.

And it's work ! There are no reason this do not work with your files.

希望我能帮助您；)

这篇关于JSDoc-将一些代码标记为不解析但保留文档?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！