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)更具可读性。