在javadoc中将长URL拆分成多行

Question

如果我使用从互联网等来源获取的代码或资源，我会在类或函数文档中指出并提供原始来源的链接。但是，写代码时我也希望遵循每行最多80个字符的原则以实现更好的可读性。有没有一种方法可以将源代码中的长URL解析为多行，并在像Eclipse这样的IDE中使用javadoc时仍保持原始地址可用？通过“可用”，我指的是在javadoc工具提示中单击URL可打开正确的页面。

例如，您将如何格式化以下内容：

/**
 * Class to do some cool stuff
 * Original source: 
 * http://stackoverflow.com/questions/and-huge-amouts-of-URL-address-which-does-not-fit-to-80-chars
 */
public class ExampleClass {

}

- pnkkr

---

我不这么认为。也许可以使用链接缩短服务？在SO上，你只需要使用URL到问题ID即可。例如，这个问题的URL是https://dev59.com/9lgR5IYBdhLWcg3wp-q5。 - yshavit

我写代码时也会坚持每行最多80个字符的原则，以增强可读性。这是一种原则，不是一条法律规定违反它就会被送进监狱。长链接不易阅读。如果您使用链接缩短服务，链接将完全变得含混不清，即无法阅读。那么您究竟想要使哪些内容易于阅读呢？即使 javadoc 源代码有一个超出80个字符的长链接，它本身也难以阅读，对吧？只需让编译后的 javadoc 易于阅读，就像 philantrovert 演示的那样。 - Andreas

我知道这不是一项法律，但有时候人们会遇到这样的事情，而我是那种容易感到烦躁并且想找到解决方法的人 :) 但现在我会暂时使用缩短链接。谢谢大家！ - pnkkr

如果您的团队使用类似Checkstyle之类的工具来强制执行代码标准，例如行长度，则这将变得相关。由于该行不能被分割，因此需要添加覆盖注释或配置以解决警告。在此示例中，我将<property name="ignorePattern" value="^ *\* *@see.+$"/>添加到了lineLength Checkstyle配置中。 - M. Justin

Answer 1

如果您不想使用URL缩短服务，可以按以下方式使用<pre></pre>标签将URL包围起来：

/**
 * Class to do some cool stuff
 * Original source: 
 * <pre>
 * See <a href="http://stackoverflow.com/questions/
   and-huge-amouts-of-URL-address-which-does-not-fit-to-80-chars">NameOfyourLink</a>
 * </pre>
 */

这将满足例如checkstyle的要求，并使您保留原始URL。

- Stuart

Answer 2

我找到的另一个解决方案是将文本分行，并确保后续行紧跟着URL（中间没有其他字符）。

例如：

/**
* Link to <a href="https://developer.android.com/reference/android/app/Service#
startForeground(int,%20android.app.Notification)">startForeground(..)</a>
*/

- Mugurel

---

这是最好的答案。它也可以与@see很好地配合使用。我唯一看到的不利之处是第三行缺少*，看起来有点丑。话虽如此，我尝试了被接受的答案（使用<pre>标签），似乎你需要删除第三行的*才能使URL在其中正常工作。此外，由于接受的答案的副作用，<pre>标签可能会影响Javadoc格式，而这种情况在这个答案中并非如此。 - Joel

Answer 3

相反，您可以使用以下方法

@see <a href = "https://stackoverflow.com/questions/and-huge-amouts-of-URL-address-which-does-not-fit-to-80-chars"> SO Link </a>

并且它将被呈现为：

另请参阅： SO 链接

来源：javadoc

- philantrovert

---

这是一种简洁的方式来缩短用户在工具提示中看到的链接，但在原始源代码中，该链接仍然超过了80个字符的限制。 - pnkkr

我认为唯一可行的解决方案是使用URL缩短工具。 - philantrovert