JSDoc - Markieren Sie einen Code, um nicht geparst zu werden, aber die Dokumentation beizubehalten?

Question

Ich versuche, eine Javascript-Datei mit JSDoc zu dokumentieren (3) wie folgt:

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

nun die Datei (genannt config.js.in) ist nicht allein gültig Javascript; Die Datei wird durch ein Makefile geführt, das einen geeigneten Wert für @HAVE_BLUETOOTH@ ersetzt.

Wenn ich versuche, JSdoc auf diesem auszuführen, wird es (verständlicherweise) wegen des Syntaxfehlers in der Datei blockiert.

Gibt es eine Möglichkeit JSDoc zu sagen alle Code in dieser Datei zu ignorieren, aber einfach berücksichtigen die Anmerkungen? (Ich muss möglicherweise zu jedem Doclet @name Tags hinzufügen, um die Dokumentation vollständig vom Code zu trennen; das ist in Ordnung).

Etwas wie:

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

Ich würde nicht lieber den Code Teil der Datei ändern, wenn möglich (I Dokumentation zu einem bestehenden Projekt hinzufügen bin). Zum Beispiel könnte ich wahrscheinlich drum herum kommen mit

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

die die Datei haben gültige JS Syntax wieder machen würde, so dass der Parser nicht beschweren, aber das bedeutet auch den Code der ursprünglichen Datei ich Modifizieren was ich vermeiden möchte (ich bevorzuge nur Dokumentation hinzufügen).

prost

Answer 1

Mein Fall ist ähnlich, weil ich JSDoc verwenden, um meine .less und .css Datei zu kommentieren. Wenn ich JSDoc auf einem Datei-Set ausführe, habe ich das gleiche Problem.

So löse ich mein Problem (mit JSDoc 3.3.3) mit dem commentsOnly JSDoc Plugin

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

Ich schaffe haben diese config.json:

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

mit der commentsOnly.js Datei in ein plugin/ Verzeichnis (in Betracht ziehen plugin/ und config.json sind in demselben Ordner) und in diesem Ordner ich den folgenden CLI-Befehl ausführen:

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

Und es ist Arbeit! Es gibt keinen Grund, dass dies nicht mit Ihren Dateien funktioniert.

Ich hoffe, ich helfe Ihnen;)