예를 들어 NodeJS 용 Q 라이브러리를 사용하여 promise 객체를 반환하는 코드가 있습니다.
var Q = require('q');
/**
* @returns ???
*/
function task(err) {
return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}
JSDoc을 사용하여 이러한 반환 값을 문서화하는 방법은 무엇입니까?
답변
Javascript에 존재하지 않더라도 JSdoc이 “일반 유형”을 이해한다는 것을 발견했습니다.
따라서 사용자 정의 유형을 정의한 다음 /* @return Promise<MyType> */. 다음 은 문서에서 사용자 정의 유형에 대한 링크가 있는 멋진 TokenConsume (token) → {Promise. <Token>} 결과 입니다 Token.
/**
* @typedef Token
* @property {bool} valid True if the token is valid.
* @property {string} id The user id bound to the token.
*/
/**
* Consume a token
* @param {string} token [description]
* @return {Promise<Token>} A promise to the token.
*/
TokenConsume = function (string) {
// bla bla
}
/* @return Promise<MyType|Error> */또는 에서도 작동합니다 /* @return Promise<MyType, Error> */.
답변
약속에 대한 외부 유형을 정의하는 경향이 있습니다.
/**
* A promise object provided by the q promise library.
* @external Promise
* @see {@link https://github.com/kriskowal/q/wiki/API-Reference}
*/
이제 프로 @return미스에 어떤 일이 발생하는지 함수 문서에 설명 할 수 있습니다 .
/**
* @return {external:Promise} On success the promise will be resolved with
* "some result".<br>
* On error the promise will be rejected with an {@link Error}.
*/
function task(err) {
return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}
답변
JSDoc을 사용하면 @typedef. 문자열 또는 배열 인 props / params가 유형의 설명에 연결되므로 이것을 꽤 많이 사용 string합니다 (예 : 문자열에 사용할 수있는 네이티브를 포함하는 typedef를 만든 경우 (아래의 JSDoc 예제 참조)). 사용자 정의 유형을 정의 할 수 있습니다. 이는 @property가 반환 내용을 나타내는 것처럼 반환에 객체 점 표기법을 사용할 수 없기 때문입니다. 따라서 객체와 같은 것을 반환하는 경우 정의를 만들 수 있습니다. 해당 유형 ( ‘ @typedef MyObject) 및 @returns {myObject} Definition of myObject.
하지만 타입은 가능한 한 리터럴이어야하고 타입을 오염시키고 싶지 않기 때문에 나는 이것에 미쳐 가지 않을 것입니다.하지만 타입을 명시 적으로 정의하고 싶은 경우가 있습니다. (좋은 예는 Modernizr입니다 … 객체를 반환하지만 문서가 없으므로 해당 반환 내용을 자세히 설명하는 사용자 정의 typedef를 만듭니다).
해당 경로로 이동할 필요가 없다면 이미 언급했듯이 pipe를 사용하여 @param, @property 또는 @return에 대해 여러 유형을 지정할 수 있습니다 |.
귀하의 경우 @throws에는 new error:을 던지기 때문에를 문서화해야합니다 * @throws {error} Throws a true new error event when the property err is undefined or not available.
//saved in a file named typedefs.jsdoc, that is in your jsdoc crawl path
/**
* @typedef string
* @author me
* @description A string literal takes form in a sequence of any valid characters. The `string` type is not the same as `string object`.
* @property {number} length The length of the string
* @property {number} indexOf The occurence (number of characters in from the start of the string) where a specifc character occurs
* @property {number} lastIndexOf The last occurence (number of characters in from the end of the string) where a specifc character occurs
* @property {string|number} charAt Gives the character that occurs in a specific part of the string
* @property {array} split Allows a string to be split on characters, such as `myString.split(' ')` will split the string into an array on blank spaces
* @property {string} toLowerCase Transfer a string to be all lower case
* @property {string} toUpperCase Transfer a string to be all upper case
* @property {string} substring Used to take a part of a string from a given range, such as `myString.substring(0,5)` will return the first 6 characters
* @property {string} substr Simialr to `substring`, `substr` uses a starting point, and then the number of characters to continue the range. `mystring.substr(2,8)` will return the characters starting at character 2 and conitnuing on for 8 more characters
* @example var myString = 'this is my string, there are many like it but this one is HOT!';
* @example
//This example uses the string object to create a string...this is almost never needed
myString = new String('my string');
myEasierString = 'my string';//exactly the same as what the line above is doing
*/
답변
현재 Jsdoc3에서 지원하는 구문 :
/**
* Retrieve the user's favorite color.
*
* @returns {Promise<string>} A promise that contains the user's favorite color
* when fulfilled.
*/
User.prototype.getFavoriteColor = function() {
// ...
};
향후 지원 되나요?
/**
* A promise for the user's favorite color.
*
* @promise FavoriteColorPromise
* @fulfill {string} The user's favorite color.
* @reject {TypeError} The user's favorite color is an invalid type.
* @reject {MissingColorError} The user has not specified a favorite color.
*/
/**
* Retrieve the user's favorite color.
*
* @returns {FavoriteColorPromise} A promise for the user's favorite color.
*/
User.prototype.getFavoriteColor = function() {
// ...
};
https://github.com/jsdoc3/jsdoc/issues/1197 에서 github 토론을 참조하십시오.
답변
DEPRECATED 일 수 있지만이를 수행하는 다른 방법도 있습니다 . 누군가 가 더 이상 사용되지 않는다고 말하고 (해당 답변에 대한 의견을 확인하십시오) 다른 사람들 은 어느 쪽이든 괜찮다고 말하기 때문에 might를 강조 하십시오 . 나는 완전성을 위해 어쨌든 그것을보고하고 있습니다.
이제 Promise.all()예를 들어 배열로 이행 된 Promise를 반환합니다. 점 표기법 스타일을 사용하면 다음과 같이 표시됩니다.
{Promise.<Array.<*>>}
JetBrains 제품 (예 : PhpStorm, WebStorm)에서 작동하며 jsforce 문서 에서도 사용됩니다 .
PHPStorm을 사용 하여 일부 문서를 자동 생성하려고 할 때 글을 쓰는 시점에는 참조가 좋지 않은 경우에도 기본적으로이 스타일이 사용됩니다.
어쨌든 다음 함수를 예로 들면 :
// NOTE: async functions always return a Promise
const test = async () => {
let array1 = [], array2 = [];
return {array1, array2};
};
내가 할 때 PhpStorm은 내가 이것을 얻을 문서를 생성합니다 :
/**
* @returns {Promise.<{array1: Array, array2: Array}>}
*/
const test = async () => {
let array1 = [], array2 = [];
return {array1, array2};
};
답변
다음은 내가하고 싶은 일입니다 (약간 과장 될 수 있음).
/**
* @external Promise
* @see {@link http://api.jquery.com/Types/#Promise Promise}
*/
/**
* This callback is called when the result is loaded.
*
* @callback SuccessCallback
* @param {string} result - The result is loaded.
*/
/**
* This callback is called when the result fails to load.
*
* @callback ErrorCallback
* @param {Error} error - The error that occurred while loading the result.
*/
/**
* Resolves with a {@link SuccessCallback}, fails with a {@link ErrorCallback}
*
* @typedef {external:Promise} LoadResultPromise
*/
/**
* Loads the result
*
* @returns {LoadResultPromise} The promise that the result will load.
*/
function loadResult() {
// do something
return promise;
}
기본적으로 일부 문서에 대한 링크를 사용하여 기본 약속을 정의하고 (이 경우에는 jQuery 하나에 연결합니다), 약속이 해결되거나 실패 할 때 호출 될 콜백을 정의한 다음 다시 연결되는 특정 약속을 정의합니다. 콜백 문서.
마지막으로 특정 약속 유형을 반환 유형으로 사용합니다.
답변
