JSDoc "@ 메서드"주석을 사용하는 것을 피할 수있는 방법이 있습니까

Question

저는 개인적으로 생성 된 문서의 팬이 아닙니다. (필자는 "Luke"소스를 읽는 사람이 많습니다.)하지만 어떻게 볼 수 있습니까? 그러한 문서화는 다른 사람들에게 유용 할 수 있습니다. 자, 일반적으로 문서 생성은 한가지를 제외하고는 저에게 영향을 미치지 않습니다 : @ 방법.

대부분의 JSDoc 주석 (예 : @param.)를 여전히 소스를 읽는 사람에게 완벽하게 유용하지만 @method 100 % 중복 :

/* 
* @param num number to add five to 
* @method addFive 
*/ 
function addFive(num) { ... 

그래서, 난 정말 @method 라인의 수백을 피하기 위해 싶습니다 우리 코드를 어수선하게 만든다. 그러나 동료는 @method이 클래스의 메소드 목록을 생성 할 수 있도록 JSDoc 생성기 (YUI를 사용하고 있습니다)에 필요하다고 생각합니다.

제 질문은 (거기에있는 JSDoc 전문가에게)입니다 : @method없이 유용한 문서 (즉, 클래스 목록의 메서드로)를 생성하는 방법이 있습니까? 또는 @method이 정말로 필요한 경우 함수 이름에서 메서드 이름을 유추 할 수있는 JSDoc 생성기가 있습니까? @method addFive 대신 @method을 사용할 수 있습니까?

P. 질문에 직접 답하는 것이 아니라 문제를 완전히 피할 수있는 방법을 제안하는 "잘못하고 있습니다"유형의 대답이 있다면 나는 그것을 듣고 싶습니다. 나는 확실히 JSDoc 전문가가 아니다.

Answer 1

동료가 정확하지 않습니다.

@method은 defined here 인 @function의 동의어 인 JSDoc3입니다.

이러한 문서의 윤곽을 따라서 @function에서 까지만 입력하면됩니다. JSDoc은 변수를 함수로 인식합니다. 이것의 예는 다음과 같습니다 당신은 '이 아닌 명백한'에 의해 (비 명백한 방법으로 객체의 멤버에 함수 객체를 할당 할 때마다

객체 관점에서

/** 
* @function 
*/ 
var func = functionGenerator.generate(); 

, 당신은 동일한 작업을 수행 할 것 , 즉 정적 분석의 관점에서 말입니다. 즉, 함수 식을 사용하지 않는 경우).

그래서,

var ageGetter = function() { 
    console.log("A lady never tells"); 
} 

var Person = { 

    name: "Gertrude", 

    getAge: ageGetter 

    getName: function() { 
    return this.name; 
    } 
} 

같은 일이 아니지만 getName를 들어, getAge에 대한 @method 또는 @function의 명시 적 사용을 필요로한다.

최종 점 : @method의 이름을 명시 적으로 포함 할 필요가 없습니다 (어떤 점에서 추측 할 수없는 경우가 아니라면, 아마도 꽤 펑키 한 인스턴스 생성을 할 것이므로 아마도 의존 할 수 없었을 것입니다). 어쨌든 자동 doc 생성에).

Answer 2

내가 틀릴 수도 있지만 JavaScript에서 여러 정의 방법으로 인해 특정 정의에 대해서는 @method이 필요합니다.

// JSDoc will recognize this as an object member 
var obj = { 
    mymethod: function() {} 
}; 

// There is no way for JSDoc to tell where my method is going to end up 
var mymethod = function() {}; 
obj.mymethod = mymethod;