Javadoc：没有 HTML 标签的换行符？答案

【问题标题】：Javadoc: line breaks without HTML-tags?Javadoc：没有 HTML 标签的换行符？
【发布时间】：2011-07-01 22:24:16
【问题描述】：

抱歉，可能是常见问题解答之类的问题，但我找不到答案。

就我所记得的 Eclipse 而言，Javadoc 注释中的空白行（在源 Javadoc 弹出窗口中）显示为换行符（带有额外的垂直间距）。

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

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

其他问题：我可以为源内 Javadoc 弹出窗口覆盖默认的 Netbeans 行为（与此相关）吗？

我说的是：

来源

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

Eclipse 解释

 Paragraph One

 Paragraph Two

Netbeans 解读

 Paragraph One Paragraph Two

【问题讨论】：

其中许多答案现在已被 NetBeans8.2 过时（取代），请参阅下面@fujy 的答案，它可以完美运行。

标签： java netbeans comments javadoc

【解决方案1】：

NetBeans 中已有一个选项 - 在 8.2 版上测试 - 允许您在 cmets 中保留新行，和/或在需要时将  标记添加到您的 Javadoc

从Tools 菜单中选择Options
转到Editor 选项卡，然后转到Formatting 选项卡
在Language 菜单中选择Java，在Category 菜单中选择Comments
如果要在 cmets 中保留新行，请选中 General 部分中的 Preserve New Lines 复选框。 这将保留新行而不添加  标记
选中Javadoc部分中的Generate "" on Blank Lines复选框如果您还想添加标签。

【讨论】：

绝对是w.r.t的最佳答案。 NetBeans 8.2。简单。但是您应该编辑它以添加它仅在您对代码执行 Format 时才真正启动（使用现有的换行符）。必须小心，如果那里已经有一些，它有时可以在第一次添加双``。此后它按预期工作。

【解决方案2】：

它与 Netbeans 无关。我怀疑您在一种情况下查看源代码，在另一种情况下查看 Javadoc 的输出。换行符在 HTML 中并不重要：ergo 输出不会显示它们。如果您想要换行符，请使用  或  。

【讨论】：

正如我在问题中提到的，Eclipse确实将空行视为段落。所以我的假设是必须通过一些javadoc配置（Netbeans或没有）来实现这一点。
Eclipse 向您显示源代码，但它的格式是。 Netbeans 6.9.1 也向您展示了源代码，同上，即它也不会忽略换行符。但是，如果您以任何方式查看 Javadoc 的 output 是否不正确，因为这意味着 not 忽略换行符。

【解决方案3】：

我不确定这是否有助于 OP 的情况，但是我将 <pre></pre> 放在我的文档周围，这样 netbean 就不会弄乱我的格式。所以它看起来像

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

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

更新：在 Netbeans 8.x 中有一个代码格式化选项可以禁用格式化 cmets。

【讨论】：

【解决方案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

【讨论】：

【解决方案5】：

我不知道 Eclipse 在这里做了什么，但如果你想要这个行为（不仅仅是一个 IDE），你可能需要创建一个新的 Doclet（它可能基于默认的 HTML doclet），那里在每个空行等处插入。

【讨论】：

【解决方案6】：

这是一个伪解决方案
（遗憾的是，它只影响生成的 javadoc，但不影响 Netbeans 的源内 javadoc 显示）。

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

div.block {
    white-space: pre;
}

【讨论】：

【解决方案7】：

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

p {
    line-height: 25px;
}

【讨论】：

谢谢，但我确信 Netbeans 根本不会将空行解释为段落（请参阅我的问题中的“Netbeans 解释”）。我的意思是：如果你有线条，你只能定义行距。
嗯。我看到了。但不确定 Netbeans 是否提供了编辑此选项的选项。