JavaDoc可能的警告NullPointerException

Question

我寫了一個方法，返回Android上最可能的LAN接口。由於用戶可能未連接到局域網，因此此方法可能返回空值。我應該如何在JavaDoc中告訴調用者這種可能性？我不認爲我應該使用@throws，因爲該方法實際上不會拋出NullPointerException。

Answer 1

我認爲這樣做的正確方法是返回子句中：

/** 
* ... 
* @return {@code null} if the user is not connected to a LAN, else the most 
* likely LAN interface. 
*/ 
public LanInterface getMostLikelyInterface(); 

這將是調用者的責任，要知道，這意味着沒有檢查之前使用返回值。

雖然你可以使用番石榴Optional類，而不是：那麼

/** 
* ... 
* @return Optional.absent if the user is not connected to a Lan interface, 
* else the most likely one. 
*/ 
public Optional<LanInterface> getMostLikelyInterface(); 

的用戶將不得不使用if(iface.isPresent())，這比if(iface != null)更具可讀性。