如何在 Javadoc 中创建多层缩进？

Question

假设您要编写代码文档 (Javadoc) 并想要使用深度缩进来表示元素之间的关系。

如何创建嵌套列表如下所示：

- 一些元素 - 另一些元素 - 再另一些元素

- James Raitsev

Answer 1

<ul>
  <li>Element</li>
  <ul>
     <li>Subelement...</li>

您可以在Javadoc注释中自由地使用HTML。

更新：因为它出现了，我尝试了一下。

<ul>
    <li>one</li>
    <ul>
        <li>one point one</li>
    </ul>   
</ul>

获取并且：

• 一个
• 一点一

我同意正确嵌套更好。

- Charlie Martin

---

我认为嵌套的<ul>必须在某个<li>元素内部，可以参考http://www.w3.org/wiki/HTML_lists#Nesting_lists 进行比较。 - user2622016

@Charlie 而不是说“我同意正确的嵌套更好”，也许你可以写一个例子来展示如何正确地嵌套？否则，也许一些初学者不会理解你的评论，并使用上述提到的形式。 - Rauni Lillemets

我理解用户2622016的意思是，您必须这样编写：<ul><li><ul>...</ul></li></ul>，以便最内层的<ul>..</ul>也在<li>..</li>块内。 - Rauni Lillemets

不过，需要做的一件事是删除</li>标签。它们不应该出现在这里。尽管Javadoc借鉴了HTML，但它并不是HTML。同样，</p>标签也是如此，在Javadoc中不应使用。 - SeverityOne

虽然我没有明确找到它（我已经查过了），但这是在Oracle文档中使用的样式。此外，NetBeans对此表示抱怨。而Intellij则愉快地添加</li>标签。 - SeverityOne

Answer 2

正确的方法如下：

/**
 * <ul>
 *   <li>some element
 *   <li><ul>
 *     <li>some other element
 *     <li><ul>
 *       <li>yet some other element
 *     </ul>
 *   </ul>
 * </ul>
 */

尽管JavaDoc借鉴了HTML，但它并不是HTML，您应该省略</li>标签，就像省略</p>标签一样。

- SeverityOne

---

省略闭合标签的参考资料？ - friederbluemle

好的，这里是链接：http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#examples - 尽管它是隐式而不是显式的。 - SeverityOne

为什么您认为省略 </p> 标签与不是 HTML 有任何关系呢？在大多数情况下，HTML 中省略 </p> 标签是合法的。这甚至在 HTML 常被手动编辑的时代是常见做法，就像 javadoc 仍然如此。 - SensorSmith

你在推断我从未说过的事情。我说的是应该省略 </p> 标签。在 HTML 中什么是合法或不合法并不是很相关。 - SeverityOne

因为它不是。有关更多信息，请参见StackOverflow上的此问题。对于允许使用哪些HTML标签存在限制。 - SeverityOne

Answer 3

嵌套列表应该放在自己的 <li> 标签内。<ul> 不是 <ul> 的有效子元素。

因此，您的示例应该是：

<ul>
  <li>some element</li>
  <li>
    <ul>
      <li>some other element</li>
      <li>
        <ul>
          <li>yet some other element</li>
        </ul>
      </li>
    </ul>
  </li>
</ul>

- Drew Noakes

---

你的代码生成了一个包含空项目的列表。虽然它在HTML中嵌套正确，但呈现出来的结果很丑。 - naXa stands with Ukraine

在这种情况下，有效的HTML似乎是无效的JavaDoc (>ლ)。 - Top-Master

Answer 4

保持Javadoc缩进的另一种简单快捷方法

<pre>...</pre>

简单来说，它会按照原文的行格式进行渲染。
在使用之前最好先与你的团队商议一下，以防万一。

例如，这样

/**
* <pre>
* - some element
*    - some other element
*       - yet some other element
* </pre>
*/

将会呈现为以下内容：

 - some element
    - some other element
       - yet some other element

优点：

• 比多层HTML嵌套更易读的代码
• 简单
• 输入速度快
• 通过tab和空格保持行缩进
• 基本上所见即所得
• 可以通过使用{@code ...}来美观地渲染代码块

缺点：

• 软换行会根据<pre>...</pre>块中最长的行进行调整，因此需要手动换行

- GreenMarty