如何修复此 ESLint/JSDoc 语法错误？
How to fix this ESLint/JSDoc syntax error?
我已经记录了这个函数...
/**
* Perform an asynchronous HTTP (Ajax) request.
*
* @param {String|Object} url A string containing the URL to which the request is sent, or the settings object.
* @param {Object=} settings A set of key/value pairs that configure the Ajax request. All settings are optional.
* @param {Object=} settings.accepts A set of key/value pairs that map a given `dataType` to its MIME type, which gets sent in the Accept request header. This header tells the server what kind of response it will accept in return.
* @param {Boolean=} settings.async By default, all requests are sent asynchronously (i.e. this is set to true by default). If you need synchronous requests, set this option to false.
* @param {Function=} settings.beforeSend A pre-request callback function that can be used to modify the jqXHR.
* @param {Boolean=} settings.cache If set to false, it will force requested pages not to be cached by the browser.
* @param {Function=} settings.complete A function to be called when the request finishes (after success and error callbacks are executed).
* @param {Object=} settings.contents An object of string/regular-expression pairs that determine how jQuery will parse the response, given its content type.
* @param {Boolean|String=} settings.contentType When sending data to the server, use this content type. Default is "application/x-www-form-urlencoded; charset=UTF-8", which is fine for most cases.
* @param {Object=} settings.context This object will be the context of all Ajax-related callbacks.
* @param {Object=} settings.converters An object containing dataType-to-dataType converters. Each converter's value is a function that returns the transformed value of the response.
* @param {Boolean=} settings.crossDomain If you wish to force a crossDomain request (such as JSONP) on the same domain, set the value of crossDomain to true. This allows, for example, server-side redirection to another domain.
* @param {Object|String|Array=} settings.data Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests.
* @param {Function=} settings.dataFilter A function to be used to handle the raw response data of XMLHttpRequest. This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function accepts two arguments: The raw data returned from the server and the 'dataType' parameter.
* @param {String=json} settings.dataType The type of data that you're expecting back from the server. If none is specified, jQuery will try to infer it based on the MIME type of the response.
* @param {Function=} settings.error A function to be called if the request fails.
* @param {Boolean=true} settings.global Whether to trigger global Ajax event handlers for this request.
* @param {Object=} settings.headers An object of additional header key/value pairs to send along with requests using the XMLHttpRequest transport.
* @param {Boolean=false} settings.ifModified Allow the request to be successful only if the response has changed since the last request. This is done by checking the Last-Modified header.
* @param {Boolean=} settings.isLocal Allow the current environment to be recognized as "local," (e.g. the filesystem), even if jQuery does not recognize it as such by default.
* @param {String|Boolean=} settings.jsonp Override the callback function name in a JSONP request.
* @param {String|Function=} settings.jsonpCallback Specify the callback function name for a JSONP request.
* @param {String=GET} settings.method The HTTP method to use for the request (e.g. "POST", "GET", "PUT").
* @param {String=} settings.mimeType A mime type to override the XHR mime type.
* @param {String=} settings.password A password to be used with XMLHttpRequest in response to an HTTP access authentication request.
* @param {Boolean=true} settings.processData By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false.
* @param {String=} settings.scriptCharset Only applies when the "script" transport is used (e.g., cross-domain requests with "jsonp" or "script" dataType and "GET" type). Sets the charset attribute on the script tag used in the request. Used when the character set on the local page is not the same as the one on the remote script.
* @param {Object=} settings.statusCode An object of numeric HTTP codes and functions to be called when the response has the corresponding code.
* @param {Function=} settings.success A function to be called if the request succeeds.
* @param {Number=} settings.timeout Set a timeout (in milliseconds) for the request.
* @param {Boolean=} settings.traditional Set this to true if you wish to use the traditional style of param serialization.
* @param {String=GET} settings.type An alias for method. A string containing the URL to which the request is sent.
* @param {String|Object=} settings.url A string containing the URL to which the request is sent, or an object to be sent to `wxu.link()`.
* @param {String=} settings.username A username to be used with XMLHttpRequest in response to an HTTP access authentication request.
* @param {Function=} settings.xhr Callback for creating the XMLHttpRequest object.
* @param {Object=} settings.xhrFields An object of fieldName-fieldValue pairs to set on the native XHR object.
* @returns {Promise.<Object>} Resolved when XHR request completes with 2xx status code, rejects otherwise
* @see https://api.jquery.com/jquery.ajax/
*/
export default function ajax(url, settings = {}) {
// *snip*
}
但是 eslint 给我这个错误：
JSDoc syntax error
仅此而已。我不知道错误在哪里。是否有一个验证 JSDocs 的工具可以给我一个精确的 line/column 数字？或者有人可以发现问题吗？
我以类似的方式记录了另一个函数（记录了所有选项），并且那个是无 lint 的，所以我认为这种格式是可以接受的。
ESLint 使用 Doctrine 来解析 JSDoc 注释。如果解析失败，ESLint 会输出解析器返回的任何内容。您可以尝试在您的 JSDoc 代码上直接使用 Doctrine，看看它是否能够提供更有意义的错误。
经过反复试验，Doctrine 似乎不喜欢参数的默认值。
var doctrine = require("doctrine");
let doc = `
/**
* Perform an asynchronous HTTP (Ajax) request.
*
* @param {String|Object} url A string containing the URL to which the request is sent, or the settings object.
* @param {Object=} settings A set of key/value pairs that configure the Ajax request. All settings are optional.
* @param {Object=} settings.accepts A set of key/value pairs that map a given \`dataType\` to its MIME type, which gets sent in the Accept request header. This header tells the server what kind of response it will accept in return.
* @param {Boolean=} settings.async By default, all requests are sent asynchronously (i.e. this is set to true by default). If you need synchronous requests, set this option to false.
* @param {Function=} settings.beforeSend A pre-request callback function that can be used to modify the jqXHR.
* @param {Boolean=} settings.cache If set to false, it will force requested pages not to be cached by the browser.
* @param {Function=} settings.complete A function to be called when the request finishes (after success and error callbacks are executed).
* @param {Object=} settings.contents An object of string/regular-expression pairs that determine how jQuery will parse the response, given its content type.
* @param {Boolean|String=} settings.contentType When sending data to the server, use this content type. Default is "application/x-www-form-urlencoded; charset=UTF-8", which is fine for most cases.
* @param {Object=} settings.context This object will be the context of all Ajax-related callbacks.
* @param {Object=} settings.converters An object containing dataType-to-dataType converters. Each converter's value is a function that returns the transformed value of the response.
* @param {Boolean=} settings.crossDomain If you wish to force a crossDomain request (such as JSONP) on the same domain, set the value of crossDomain to true. This allows, for example, server-side redirection to another domain.
* @param {Object|String|Array=} settings.data Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests.
* @param {Function=} settings.dataFilter A function to be used to handle the raw response data of XMLHttpRequest. This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function accepts two arguments: The raw data returned from the server and the 'dataType' parameter.
* @param {String=json} settings.dataType The type of data that you're expecting back from the server. If none is specified, jQuery will try to infer it based on the MIME type of the response.
* @param {Function=} settings.error A function to be called if the request fails.
* @param {Boolean=true} settings.global Whether to trigger global Ajax event handlers for this request.
* @param {Object=} settings.headers An object of additional header key/value pairs to send along with requests using the XMLHttpRequest transport.
* @param {Boolean=false} settings.ifModified Allow the request to be successful only if the response has changed since the last request. This is done by checking the Last-Modified header.
* @param {Boolean=} settings.isLocal Allow the current environment to be recognized as "local," (e.g. the filesystem), even if jQuery does not recognize it as such by default.
* @param {String|Boolean=} settings.jsonp Override the callback function name in a JSONP request.
* @param {String|Function=} settings.jsonpCallback Specify the callback function name for a JSONP request.
* @param {String=} settings.mimeType A mime type to override the XHR mime type.
* @param {String=} settings.password A password to be used with XMLHttpRequest in response to an HTTP access authentication request.
* @param {Boolean=true} settings.processData By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false.
* @param {String=} settings.scriptCharset Only applies when the "script" transport is used (e.g., cross-domain requests with "jsonp" or "script" dataType and "GET" type). Sets the charset attribute on the script tag used in the request. Used when the character set on the local page is not the same as the one on the remote script.
* @param {Object=} settings.statusCode An object of numeric HTTP codes and functions to be called when the response has the corresponding code.
* @param {Function=} settings.success A function to be called if the request succeeds.
* @param {Number=} settings.timeout Set a timeout (in milliseconds) for the request.
* @param {Boolean=} settings.traditional Set this to true if you wish to use the traditional style of param serialization.
* @param {String=GET} settings.type An alias for method. A string containing the URL to which the request is sent.
* @param {String|Object=} settings.url A string containing the URL to which the request is sent, or an object to be sent to \`wxu.link()\`.
* @param {String=} settings.username A username to be used with XMLHttpRequest in response to an HTTP access authentication request.
* @param {Function=} settings.xhr Callback for creating the XMLHttpRequest object.
* @param {Object=} settings.xhrFields An object of fieldName-fieldValue pairs to set on the native XHR object.
* @returns {Promise.<Object>} Resolved when XHR request completes with 2xx status code, rejects otherwise
* @see https://api.jquery.com/jquery.ajax/
*/
`;
var ast = doctrine.parse(doc, {unwrap: true, recoverable: false});
var util = require('util');
console.log(util.inspect(ast.tags.map(t => ([t.title, t.name])), {depth: 5, colors: true}));
这输出：
[ [ 'param', 'url' ],
[ 'param', 'settings' ],
[ 'param', 'settings.accepts' ],
[ 'param', 'settings.async' ],
[ 'param', 'settings.beforeSend' ],
[ 'param', 'settings.cache' ],
[ 'param', 'settings.complete' ],
[ 'param', 'settings.contents' ],
[ 'param', 'settings.contentType' ],
[ 'param', 'settings.context' ],
[ 'param', 'settings.converters' ],
[ 'param', 'settings.crossDomain' ],
[ 'param', 'settings.data' ],
[ 'param', 'settings.dataFilter' ] ]
删除所有默认值使其完成解析。我无法弄清楚如何使用参数名称语法周围的方括号来指定 default values，所以我想必须这样做。
我已经记录了这个函数...
/**
* Perform an asynchronous HTTP (Ajax) request.
*
* @param {String|Object} url A string containing the URL to which the request is sent, or the settings object.
* @param {Object=} settings A set of key/value pairs that configure the Ajax request. All settings are optional.
* @param {Object=} settings.accepts A set of key/value pairs that map a given `dataType` to its MIME type, which gets sent in the Accept request header. This header tells the server what kind of response it will accept in return.
* @param {Boolean=} settings.async By default, all requests are sent asynchronously (i.e. this is set to true by default). If you need synchronous requests, set this option to false.
* @param {Function=} settings.beforeSend A pre-request callback function that can be used to modify the jqXHR.
* @param {Boolean=} settings.cache If set to false, it will force requested pages not to be cached by the browser.
* @param {Function=} settings.complete A function to be called when the request finishes (after success and error callbacks are executed).
* @param {Object=} settings.contents An object of string/regular-expression pairs that determine how jQuery will parse the response, given its content type.
* @param {Boolean|String=} settings.contentType When sending data to the server, use this content type. Default is "application/x-www-form-urlencoded; charset=UTF-8", which is fine for most cases.
* @param {Object=} settings.context This object will be the context of all Ajax-related callbacks.
* @param {Object=} settings.converters An object containing dataType-to-dataType converters. Each converter's value is a function that returns the transformed value of the response.
* @param {Boolean=} settings.crossDomain If you wish to force a crossDomain request (such as JSONP) on the same domain, set the value of crossDomain to true. This allows, for example, server-side redirection to another domain.
* @param {Object|String|Array=} settings.data Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests.
* @param {Function=} settings.dataFilter A function to be used to handle the raw response data of XMLHttpRequest. This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function accepts two arguments: The raw data returned from the server and the 'dataType' parameter.
* @param {String=json} settings.dataType The type of data that you're expecting back from the server. If none is specified, jQuery will try to infer it based on the MIME type of the response.
* @param {Function=} settings.error A function to be called if the request fails.
* @param {Boolean=true} settings.global Whether to trigger global Ajax event handlers for this request.
* @param {Object=} settings.headers An object of additional header key/value pairs to send along with requests using the XMLHttpRequest transport.
* @param {Boolean=false} settings.ifModified Allow the request to be successful only if the response has changed since the last request. This is done by checking the Last-Modified header.
* @param {Boolean=} settings.isLocal Allow the current environment to be recognized as "local," (e.g. the filesystem), even if jQuery does not recognize it as such by default.
* @param {String|Boolean=} settings.jsonp Override the callback function name in a JSONP request.
* @param {String|Function=} settings.jsonpCallback Specify the callback function name for a JSONP request.
* @param {String=GET} settings.method The HTTP method to use for the request (e.g. "POST", "GET", "PUT").
* @param {String=} settings.mimeType A mime type to override the XHR mime type.
* @param {String=} settings.password A password to be used with XMLHttpRequest in response to an HTTP access authentication request.
* @param {Boolean=true} settings.processData By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false.
* @param {String=} settings.scriptCharset Only applies when the "script" transport is used (e.g., cross-domain requests with "jsonp" or "script" dataType and "GET" type). Sets the charset attribute on the script tag used in the request. Used when the character set on the local page is not the same as the one on the remote script.
* @param {Object=} settings.statusCode An object of numeric HTTP codes and functions to be called when the response has the corresponding code.
* @param {Function=} settings.success A function to be called if the request succeeds.
* @param {Number=} settings.timeout Set a timeout (in milliseconds) for the request.
* @param {Boolean=} settings.traditional Set this to true if you wish to use the traditional style of param serialization.
* @param {String=GET} settings.type An alias for method. A string containing the URL to which the request is sent.
* @param {String|Object=} settings.url A string containing the URL to which the request is sent, or an object to be sent to `wxu.link()`.
* @param {String=} settings.username A username to be used with XMLHttpRequest in response to an HTTP access authentication request.
* @param {Function=} settings.xhr Callback for creating the XMLHttpRequest object.
* @param {Object=} settings.xhrFields An object of fieldName-fieldValue pairs to set on the native XHR object.
* @returns {Promise.<Object>} Resolved when XHR request completes with 2xx status code, rejects otherwise
* @see https://api.jquery.com/jquery.ajax/
*/
export default function ajax(url, settings = {}) {
// *snip*
}
但是 eslint 给我这个错误：
JSDoc syntax error
仅此而已。我不知道错误在哪里。是否有一个验证 JSDocs 的工具可以给我一个精确的 line/column 数字？或者有人可以发现问题吗？
我以类似的方式记录了另一个函数（记录了所有选项），并且那个是无 lint 的，所以我认为这种格式是可以接受的。
ESLint 使用 Doctrine 来解析 JSDoc 注释。如果解析失败，ESLint 会输出解析器返回的任何内容。您可以尝试在您的 JSDoc 代码上直接使用 Doctrine，看看它是否能够提供更有意义的错误。
经过反复试验，Doctrine 似乎不喜欢参数的默认值。
var doctrine = require("doctrine");
let doc = `
/**
* Perform an asynchronous HTTP (Ajax) request.
*
* @param {String|Object} url A string containing the URL to which the request is sent, or the settings object.
* @param {Object=} settings A set of key/value pairs that configure the Ajax request. All settings are optional.
* @param {Object=} settings.accepts A set of key/value pairs that map a given \`dataType\` to its MIME type, which gets sent in the Accept request header. This header tells the server what kind of response it will accept in return.
* @param {Boolean=} settings.async By default, all requests are sent asynchronously (i.e. this is set to true by default). If you need synchronous requests, set this option to false.
* @param {Function=} settings.beforeSend A pre-request callback function that can be used to modify the jqXHR.
* @param {Boolean=} settings.cache If set to false, it will force requested pages not to be cached by the browser.
* @param {Function=} settings.complete A function to be called when the request finishes (after success and error callbacks are executed).
* @param {Object=} settings.contents An object of string/regular-expression pairs that determine how jQuery will parse the response, given its content type.
* @param {Boolean|String=} settings.contentType When sending data to the server, use this content type. Default is "application/x-www-form-urlencoded; charset=UTF-8", which is fine for most cases.
* @param {Object=} settings.context This object will be the context of all Ajax-related callbacks.
* @param {Object=} settings.converters An object containing dataType-to-dataType converters. Each converter's value is a function that returns the transformed value of the response.
* @param {Boolean=} settings.crossDomain If you wish to force a crossDomain request (such as JSONP) on the same domain, set the value of crossDomain to true. This allows, for example, server-side redirection to another domain.
* @param {Object|String|Array=} settings.data Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests.
* @param {Function=} settings.dataFilter A function to be used to handle the raw response data of XMLHttpRequest. This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function accepts two arguments: The raw data returned from the server and the 'dataType' parameter.
* @param {String=json} settings.dataType The type of data that you're expecting back from the server. If none is specified, jQuery will try to infer it based on the MIME type of the response.
* @param {Function=} settings.error A function to be called if the request fails.
* @param {Boolean=true} settings.global Whether to trigger global Ajax event handlers for this request.
* @param {Object=} settings.headers An object of additional header key/value pairs to send along with requests using the XMLHttpRequest transport.
* @param {Boolean=false} settings.ifModified Allow the request to be successful only if the response has changed since the last request. This is done by checking the Last-Modified header.
* @param {Boolean=} settings.isLocal Allow the current environment to be recognized as "local," (e.g. the filesystem), even if jQuery does not recognize it as such by default.
* @param {String|Boolean=} settings.jsonp Override the callback function name in a JSONP request.
* @param {String|Function=} settings.jsonpCallback Specify the callback function name for a JSONP request.
* @param {String=} settings.mimeType A mime type to override the XHR mime type.
* @param {String=} settings.password A password to be used with XMLHttpRequest in response to an HTTP access authentication request.
* @param {Boolean=true} settings.processData By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false.
* @param {String=} settings.scriptCharset Only applies when the "script" transport is used (e.g., cross-domain requests with "jsonp" or "script" dataType and "GET" type). Sets the charset attribute on the script tag used in the request. Used when the character set on the local page is not the same as the one on the remote script.
* @param {Object=} settings.statusCode An object of numeric HTTP codes and functions to be called when the response has the corresponding code.
* @param {Function=} settings.success A function to be called if the request succeeds.
* @param {Number=} settings.timeout Set a timeout (in milliseconds) for the request.
* @param {Boolean=} settings.traditional Set this to true if you wish to use the traditional style of param serialization.
* @param {String=GET} settings.type An alias for method. A string containing the URL to which the request is sent.
* @param {String|Object=} settings.url A string containing the URL to which the request is sent, or an object to be sent to \`wxu.link()\`.
* @param {String=} settings.username A username to be used with XMLHttpRequest in response to an HTTP access authentication request.
* @param {Function=} settings.xhr Callback for creating the XMLHttpRequest object.
* @param {Object=} settings.xhrFields An object of fieldName-fieldValue pairs to set on the native XHR object.
* @returns {Promise.<Object>} Resolved when XHR request completes with 2xx status code, rejects otherwise
* @see https://api.jquery.com/jquery.ajax/
*/
`;
var ast = doctrine.parse(doc, {unwrap: true, recoverable: false});
var util = require('util');
console.log(util.inspect(ast.tags.map(t => ([t.title, t.name])), {depth: 5, colors: true}));
这输出：
[ [ 'param', 'url' ],
[ 'param', 'settings' ],
[ 'param', 'settings.accepts' ],
[ 'param', 'settings.async' ],
[ 'param', 'settings.beforeSend' ],
[ 'param', 'settings.cache' ],
[ 'param', 'settings.complete' ],
[ 'param', 'settings.contents' ],
[ 'param', 'settings.contentType' ],
[ 'param', 'settings.context' ],
[ 'param', 'settings.converters' ],
[ 'param', 'settings.crossDomain' ],
[ 'param', 'settings.data' ],
[ 'param', 'settings.dataFilter' ] ]
删除所有默认值使其完成解析。我无法弄清楚如何使用参数名称语法周围的方括号来指定 default values，所以我想必须这样做。