jsdoc로 익명 객체와 함수를 문서화하는 가장 좋은 방법

jsdoc로 익명 객체와 함수를 문서화하는 가장 좋은 방법

---

편집 : 이것은 기술적으로 두 부분으로 구성된 질문입니다. 일반적으로 질문을 다루고 특정 질문을 처리하는 답변과 연결된 베스트 답변을 선택했습니다.

jsdoc로 익명 객체와 함수를 문서화하는 가장 좋은 방법은 무엇입니까?

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

어느 PageRequest개체 또는 callback코드에 존재합니다. getPage()런타임시 제공 됩니다. 하지만 객체와 기능이 무엇인지 정의하고 싶습니다.

다음 PageRequest을 문서화하기 위해 객체를 생성 할 수 있습니다 .

/**
 * @namespace {PageRequest} Object specification
 * @property {String} pageId ID of the page you want.
 * @property {String} pageName Name of the page you want.
 */
var PageRequest = {
    pageId : null,
    pageName : null
};

그리고 괜찮습니다 (이 작업을 수행하는 더 나은 방법에 대해 열려 있지만).

callback기능 을 문서화하는 가장 좋은 방법은 무엇입니까 ? 예를 들어 콜백 함수가 다음과 같은 형식임을 문서에서 알리고 싶습니다.

callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)

이 작업을 수행하는 방법에 대한 아이디어가 있습니까?

---

@name 태그를 사용하여 코드에 존재하지 않는 내용을 문서화 할 수 있습니다.

        /** Description of the function
            @name IDontReallyExist
            @function
            @param {String} someParameter Description
        */


        /** The CallAgain method calls the provided function twice
            @param {IDontReallyExist} func The function to call twice
        */
        exports.CallAgain = function(func) { func(); func(); }

다음은 @name 태그 문서 입니다. 이름 경로도 유용 할 수 있습니다.

---

당신은 사용할 수 있습니다 @callback또는 @typedef.

/**
 * @callback arrayCallback
 * @param  {object} element - Value of array element
 * @param  {number} index   - Index of array element
 * @param  {Array}  array   - Array itself
 */

/**
 * @param {arrayCallback} callback - function applied against elements
 * @return {Array} with elements transformed by callback
 */
Array.prototype.map = function(callback) { ... }

---

studgeek의 답변을 칭찬하기 위해 JsDoc with Google Closure Compiler를 사용하여 수행 할 수있는 작업 을 보여주는 예제를 제공했습니다 .

문서화 된 익명 유형은 생성 된 축소 된 파일에서 제거되고 컴파일러는 유효한 객체가 전달되는지 확인합니다 (가능한 경우). 그러나 컴파일러를 사용하지 않더라도 WebStorm (IntelliJ)과 같은 다음 개발자 및 도구가이를 이해하고 코드 완성을 제공하는 데 도움이 될 수 있습니다.

// This defines an named type that you don't need much besides its name in the code
// Look at the definition of Page#getPage which illustrates defining a type inline
/**  @typedef { pageId : string, pageName : string, contents: string} */
var PageResponse;

/**
 * @class {Page} Page Class specification
 */
var Page = function() {    
    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     *
     * The type for the second parameter for the function below is defined inline
     *
     * @param {function(PageResponse, {statusCode: number, statusMsg: string})} callback
     *        Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

---

@link 메서드와 클래스에 인라인 링크를 추가 할 수 있습니다.

/**
 * Get a page from the server
 * @param {PageRequest} pageRequest Info on the page you want to request
 * @param {function} callback Function executed when page is retrieved<br />
 * function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus)
 */
this.getPage = function (pageRequest, callback) {
};

이상적이지는 않지만 작업을 완료합니다.

---

The Google Closure Compiler Annotations has Type Expressions for this which includes the ability to indicate type for specific arguments, return type, and even this. Many libraries are looking at following the Google Closure Compiler Annotations, because they want to use it to shrink their code. So it's got some momentum. The downside is I don't see a way to give the description.

For providing the description perhaps the JSDoc Toolkit Parameters With Properties approach would work (look at the bottom of the page). It's what I am doing right now. The JSDoc Toolkit is prepping to start work on V3, so feedback there might be good.

---

You could use @see to link to another method within the same class. The method would never be used, it would just be there for documentation purposes.

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     * @see #getPageCallback 
     */
    this.getPage = function (pageRequest, callback) {
    }; 

    /**
     * Called when page request completes 
     * @param {PageResponse} pageResponse The requested page
     * @param {PageRequestStatus} pageRequestStatus Status of the page
     */
    //#ifdef 0
    this.getPageCallback = function (pageResponse, pageRequestStatus) { };
    //#endif 
};

If you are using some kind of build system, the dummy method could easily be omitted from the build.

참고URL : https://stackoverflow.com/questions/3171454/best-way-to-document-anonymous-objects-and-functions-with-jsdoc