Javadoc：如何在没有HTML标签的情况下换行？

Question

很抱歉问一个可能是常见问题，但我就是找不到答案。

据我所知，在 Eclipse 中，Javadoc 注释中的空行会被显示为换行（在源代码中的 Javadoc 弹出窗口中，带有额外的垂直间距）。

然而，在 Netbeans 中，情况并非如此。

我可以配置 Javadoc 将空行解释为换行吗？

附加问题：我是否可以覆盖与此相关的默认 Netbeans 行为（用于源代码中的 Javadoc 弹出窗口）？

我所说的是：

Source

/**
 * Paragraph One
 *
 * Paragraph Two
 */
 void someMethod() { }

Eclipse解释

 Paragraph One

 Paragraph Two

Netbeans解释

 Paragraph One Paragraph Two

- java.is.for.desktop

---

许多这些答案现在已经过时（被NetBeans8.2取代），请参见下面@fujy的答案，它完美地工作。 - Webel IT Australia - upvoter

Answer 1

这与Netbeans无关。我怀疑你在一个情况下查看源代码，在另一个情况下查看Javadoc的输出结果。在HTML中，换行符并不重要：因此输出结果不会显示它们。如果你想要一个新行，请使用<p>或<br>。

- user207421

---

正如我在问题中提到的，Eclipse 将空行视为段落。因此，我的假设是可以通过某些 javadoc 配置（无论是使用 Netbeans 还是不使用）实现这一点。 - java.is.for.desktop

Eclipse可以显示源代码，无论格式如何。Netbeans 6.9.1也可以显示源代码，同样不会忽略换行符。但是，如果您正在查看Javadoc的输出结果，则任何方式都不应该忽略换行符，否则会产生错误。 - user207421

Answer 2

我不确定这是否有助于OP的情况，但是我在我的文档周围加上了<pre></pre>，以便Netbean不会破坏我的格式。这样它看起来就像

/**
 * <pre>
 * Paragraph One
 *
 * Paragraph Two
 * </pre>
 */

这是我最接近以文本格式显示新行的方式。我正在使用NetBeans 7.1.2。这样使用 代码格式 选项将不会重新格式化文档。在提示中显示文档仍然有格式。

更新：在NetBeans 8.x中，有一个选项可以禁用格式化注释。

- AaA

---

这个很好，但是有一个缺点。它会破坏软换行，对于长行文本来说会变得很明显。比如，如果你的IDE显示像javadoc一样的"工具提示"，它会变得和行一样长，直到行的末尾，迫使你向右滚动。 - undefined

@GreenMarty，哪个版本？7还是8的解决方案？对于8，你将不再需要使用pre标签。对于7，从技术上讲，你需要根据你的代码宽度（通常由公司规定，对我来说是160个字符）换行，这意味着你仍然可以看到整个文档，因为它的字体比代码本身要小。不管怎样，我在2018年左右停止使用NetBeans，转而使用InteliJ，它没有这个问题（但并不意味着它没有其他问题 ;) ）。 - undefined

我也使用最新的IntelliJ。当我在<pre></pre>标签中编写长行时，在渲染的javadocs“工具提示”中会得到长行。据我所知，这行永远不会换行。我认为这是有意为之的，以防止例如{@code...}在“工具提示”视图中被换行。 - undefined

@GreenMarty，这是正确的，使用预格式化可以阻止文档重新格式化，并按原样显示。所以如果你需要文档换行，你需要自己加入换行符。 - undefined

我明白了，我以为你说的是，在Intellij Idea中不是这样工作的，所以我回答说在Intellij中也不会换行。 - undefined

Answer 3

在 NetBeans 中已经有一个选项 - 在版本 8.2 上测试过 - 可以使你保留注释中的换行符，并/或者在需要时将 <p> 标签添加到你的 Javadoc 中。

• 从 Tools 菜单中选择 Options
• 进入 Editor 选项卡，然后进入 Formatting 选项卡
• 在 Language 菜单中选择 Java，并在 Category 菜单中选择 Comments
• 如果你想保留注释中的换行符，请在 General 部分中勾选 Preserve New Lines 复选框。这将保留换行符而不添加 <p> 标签。
• 如果你还想添加 <p> 标签，请在 Javadoc 部分中勾选 Generate "<p>" on Blank Lines 复选框。

- fujy

---

绝对是关于NetBeans 8.2最好的答案。很容易。但您应该编辑它以添加仅在执行代码格式化（带有现有换行符）时才实际启动的内容。如果已经手动添加了一些<p>，第一次有时会添加双重<p>``<p>。之后它将按预期工作。 - Webel IT Australia - upvoter

Answer 4

我同意你的观点，HTML不应该出现在源代码中。可惜的是，我在谷歌上查找这方面的帮助时并没有得到很多有用的结果。实际上，实现这个功能非常容易。

以下是可以编译和使用的自定义 Doclet：

import com.sun.javadoc.*;
import com.sun.tools.doclets.standard.*;

/**
 * Formats text-only comments with HTML.
 */
@SuppressWarnings("restriction")
public final class TextDoclet {
    private static final Pattern NEWLINE_REGEX = Pattern.compile("\\n");
    private static final String BR = "<br/>\n";

    public static boolean start(RootDoc rootDoc) {
        for ( ClassDoc classdoc : rootDoc.classes())
            classdoc.setRawCommentText(formatText(classdoc.getRawCommentText()));

        return Standard.start(rootDoc);     
    }

    private static String formatText(String text) {
        return NEWLINE_REGEX.matcher(text).replaceAll(BR);
    }
}

使用javadoc调用它的示例：

javadoc -docletpath ~/project/text-doclet/target/text-doclet-1.0.0-SNAPSHOT.jar -doclet com.myorg.textdoclet.TextDoclet -sourcepath ~/project/myapp/src/main/java -subpackages com.myorg.myapp

- roylaurie

Answer 5

JavaDoc显示了CSS样式的定义方式。您可以编辑与段落标签相关联的CSS样式来执行此操作：

JavaDoc显示CSS样式的定义方式。您可以编辑与段落标签相关联的CSS样式来实现此目的：

p {
    line-height: 25px;
}

- adarshr

---

谢谢，但我确定Netbeans根本不会将空行解释为段落（请参见我问题中的“Netbeans解释”）。我的意思是：只有在有行时才能定义行间距。 - java.is.for.desktop

嗯，我看到了。但我不确定Netbeans是否提供编辑此选项的选项。 - adarshr

Answer 6

这是一种伪解决方案
（遗憾的是，它只影响生成的javadoc，而不影响Netbeans的源代码中的javadoc显示）。

指定一个包含以下内容的样式表：

div.block {
    white-space: pre;
}

- java.is.for.desktop

Answer 7

我不知道Eclipse在这里做什么，但如果你想要这种行为（不仅仅是在IDE中），你可能需要创建一个新的Doclet（可以基于默认的HTML doclet），在其中每个空行插入<p>或类似的标记。

- Paŭlo Ebermann