JSDoc - marquer un certain code pour qu'il ne soit pas analysé mais conserver la documentation ?

Question

J'essaie de documenter un fichier Javascript avec JSDoc(3) comme suit :

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

Maintenant, le fichier (appelé config.js.in ) n'est pas en soi un Javascript valide ; le fichier est exécuté par un Makefile qui substitue une valeur appropriée pour @HAVE_BLUETOOTH@ .

Lorsque j'essaie d'exécuter JSdoc sur ce fichier, il se rebiffe (ce qui est compréhensible) à cause d'une erreur de syntaxe dans le fichier.

Existe-t-il un moyen de dire à JSDoc d'ignorer todos le code dans ce fichier mais simplement prendre en compte les annotations ? (Je devrais peut-être ajouter @name à chaque doclet pour séparer complètement la documentation du code ; c'est bien).

Quelque chose comme :

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

Je préférerais ne pas modifier la partie code du fichier, si possible (j'ajoute de la documentation à un projet existant). Par exemple, je pourrais probablement contourner le problème avec

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

ce qui permettrait au fichier d'avoir à nouveau une syntaxe JS valide afin que l'analyseur syntaxique ne se plaigne pas, mais cela signifie également que je modifie le code du fichier original, ce que je veux éviter (je préfère que juste ajouter de la documentation).

salutations

Answer 1

Mon cas est similaire car j'utilise JSDoc pour commenter mes .less y .css dossier. Lorsque j'exécute JSDoc sur un ensemble de fichiers, j'ai le même problème.

J'ai donc résolu mon problème (avec JSDoc 3.3.3) avec la méthode suivante commentsOnly Plugin JSDoc

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

J'ai créé ceci config.json :

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

avec le commentsOnly.js dans un fichier plugin/ (considérer plugin/ y config.json sont dans le même dossier) et dans ce dossier j'exécute la commande CLI suivante :

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

Et c'est du travail ! Il n'y a aucune raison pour que cela ne fonctionne pas avec vos fichiers.

J'espère vous aider ;)