JSDoc - đánh dấu một số mã để không được phân tích cú pháp nhưng vẫn giữ lại tài liệu?

Question

Tôi đang cố gắng để ghi lại một tập tin Javascript với JSDoc (3) như sau:

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

Bây giờ tập tin (gọi tắt là config.js.in) không có trong javascript có giá trị riêng của mình; tệp được chạy thông qua một Makefile thay thế một giá trị thích hợp cho @HAVE_BLUETOOTH@.

Khi tôi cố gắng chạy JSdoc trên này, nó (dễ hiểu) balks vì lỗi cú pháp trong tệp.

Có cách nào để yêu cầu JSDoc bỏ qua tất cả mã trong tệp này nhưng chỉ cần tính đến chú thích? (Tôi có thể phải thêm @name thẻ vào mỗi doclet để hoàn toàn tách biệt tài liệu khỏi mã; điều đó tốt).

Cái gì như:

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

tôi không muốn thay đổi phần mã của tập tin, nếu có thể (tôi thêm tài liệu để một dự án hiện có). Ví dụ, tôi có lẽ có thể nhận được xung quanh nó với

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

mà sẽ làm cho các tập tin có cú pháp JS hợp lệ một lần nữa để phân tích cú pháp không phàn nàn, nhưng điều này cũng có nghĩa là tôi đang sửa đổi mã của tập tin gốc mà tôi muốn tránh (tôi thích chỉ cần thêm tài liệu).

cổ vũ

Answer 1

trường hợp của tôi cũng tương tự vì tôi sử dụng JSDoc bình luận của tôi tập .less và .css. Khi tôi chạy JSDoc trên tập hợp các tập tin, tôi có cùng một vấn đề.

Vì vậy, tôi giải quyết vấn đề của tôi (với JSDoc 3.3.3) với các plugin commentsOnly JSDoc

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

Tôi có tạo này config.json:

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

với commentsOnly.js tệp vào thư mục plugin/ (xem plugin/ và config.json nằm trong cùng một thư mục) và trong thư mục này, tôi thực hiện lệnh CLI sau:

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

Và nó hoạt động! Không có lý do nào không làm việc với các tệp của bạn.

Hy vọng tôi sẽ giúp bạn;)