JSDoc - mark some code to not be parsed but retain documentation?

问题

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@;

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@.

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

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).

Something like:

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

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).

cheers

回答1:

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.

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

I have create this config.json:

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

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.

Hope I help you ;)

来源：https://stackoverflow.com/questions/12890682/jsdoc-mark-some-code-to-not-be-parsed-but-retain-documentation

标签

jsdoc