JsDoc에서 반환 된 데이터를 문서화하는 방법

Question

요청 된 JSON 결과를 서버에 문서화하려면 어떻게해야합니까?

위의 예제에서

/** 
* Gets a user's data 
* @returns {jQuery} 
*/ 
function getUserData(userId){ 
    return $.get('/usr/' + userId); 
} 

반환 된 데이터는

{ 
    "name" : "Bob", 
    "status" : 2 
} 

Answer 1

/** 
* Gets a user's data request 
* @return {jQuery.jqXHR} 
*/ 
function getUserData(userId){ 
    return $.getJSON('/usr/' + userId); 
} 

/* 
* Handles the result of a user data request. 
* @param {Object} data The JSON object, already converted to an Object. 
*/ 
function doSomethingWithUserData(data) { 
    console.log('do something with user data:', data); 
} 

getUserData(userId).done(handleUserData); 

펠릭스 지적한 것처럼 JSON의 대상이되는 것, 반환 값은 JSON이 아닌, 그것의 심지어는 객체가 아닙니다.

견적 JQuery's types documentation 다음 $ 아약스() 메소드는 XMLHttpRequest 객체의 상위 인 jqXHR 객체를 반환 jQuery를 1.5로서

. 자세한 내용은 $.get 때문에 $ 아약스 항목

의 jqXHR 섹션을 참조하고 $.getJSON이 $.ajax 모두 shorthands 있으며, 같은이 적용됩니다.

예에서는 약속 및 처리기를 사용하고 있습니다. 처리기에서 함수를 작성하여 더 명확하게 문서화 할 수 있지만 익명의 함수로 처리하는 경우가 많습니다.

$.get을 $.getJSON으로 변환 했으므로 JSON.parse 호출 (문자열에서 객체로 답장 함)이 수행됩니다. $.get의 처리기는 대신 @param {string}을 사용합니다. 코멘트 OP에서

업데이트는 향후 디바이스가 호출에 무엇을 기대해야하는지 알 것이다 그래야 사용자 정의 데이터와 함께이 문제를 처리하는 방법을 물었다.

이제 데이터를 확인 했으므로 문서화 해 보겠습니다.

복잡성 및 초기화가 필요한 경우 문서화를위한 3 가지 좋은 해결책이 있습니다.

@property를 사용하여 @typedef를 만들어 속성을 설명하는 것이 가장 간단합니다. 추가 코드가 필요하지 않으며 전적으로 설명서입니다. 사용

goog.provide('UserData'); 
/* 
* UserData (in the style of Closure's JSDocs) 
* @typedef {{ 
* name: {string}, 
* title: {string} 
* }} 
*/ 
UserData; 

또는

/* 
* UserData (in the style of useJSDocs) 
* @typedef {Object} 
* @property {string} name 
* @property {string} title 
*/ 
var UserData; 

:

/* 
* Handles the result of a user data request. 
* @param {UserData} data The JSON object, already converted to an Object, 
* cast to UserData 
*/ 
function doSomethingWithUserData(data) { 
    console.log('do something with user data:', data); 
} 

와 유사하며, 당신에게 더 유용 할 수 있습니다 @interface @record.

마지막으로 몇 가지 기본 설정/초기화 라인을 수집하여 클래스에 배치 할 수 있다면 let user = new UserData(jsonUser)의 직선 클래스가 있습니다. 이것이 제가 제안하는 방법입니다.