有沒有什麼辦法可以避免使用JSDoc「@method」註釋

我不是個人生成文檔的大粉絲（我更像是一個「讀盧克源」的人），但我可以看到這種文件可能對其他人有用。現在，通常他們的文檔生成不會影響我，除了一件事情：@method。有沒有什麼辦法可以避免使用JSDoc「@method」註釋

大多數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代替@method addFive？

P.S.如果有「你做錯了」類型的答案，並不直接回答這個問題，但提出了一種完全避免問題的方法，我很樂意聽到它;我當然不是JSDoc專家。

來源

2012-07-26 machineghost

JSDoc 3，對吧？ – Dancrumb 2012-08-03 16:23:31

你的同事並不嚴格正確。

@method是JSDoc3擴展名，它是@function的同義詞，它是defined here。

正如那些文檔概述，您只需要使用@function到force 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; 
    } 
}

需要明確使用@method或@function爲getAge，而不是getName。

最後一點：你不需要明確包含@method這個名字，除非這也不可能推斷出來（在這一點上，你可能做了一些非常有趣的實例化，所以可能無法依靠無論如何，對於自動文檔生成）。

來源

2012-08-03 16:33:14 Dancrumb

我可能在這裏是錯的，但由於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;

來源

2012-07-28 20:10:32

有沒有什麼辦法可以避免使用JSDoc「@method」註釋

回答

相關問題