在Javadocs中，我应该如何在<code>标签中写复数形式的单数对象？

Question

我有一个名为 Identity 的 class。在我的 javadoc 评论中，我将其作为复数形式引用。我可以想到两个解决方案：将引用更改为 <code>Identities</code> 或 <code>Identity</code>s。感觉这两个都不对，不知道有没有更好的解决办法

为了清楚起见，这里有一个例子：

/**
  * Returns an <code>IdentityBank</code> of <code>Identity</code>s with the given sex.
  */

或

/**
  * Returns an <code>IdentityBank</code> of <code>Identities</code> with the given sex.
  */

Answer 1

听起来你想在这里做两件事：使用良好的语法，但也使用你的 classes 的文字，逐字的名称，以便你的 javadoc 的用户可以查找它们。

在处理复数时，您可以做的一件事是使用短语 "X instances"。因此，使用您的示例，您可以输入：

/**
 * Returns an <code>IdentityBank</code> of <code>Identity</code> instances with the given sex.
 */

如果你需要指定一个值类型的复数（它本身没有实例），你可以使用"X values"。例如，您可以说 "Returns a list of int values"。其他可接受的名称可能是 "records"、"notes"、"entries"、"notices"，或者如 @Marco13 所述，"objects".

您应该避免在您的框架、系统或应用程序中使用与现有技术术语或 class 名称冲突的术语，除非您正在使用该术语，因为它已被使用。例如，除非您指的是文件系统中的文字文件，否则不要说 "returns a list of Case files"。使用它来指代文件的 业务规则 概念会增加混淆的可能性。由于这个原因要考虑避免的其他术语可能是 "databases"、"tables"（除非指的是数据库中的实际表或它们的抽象或表示）、"pages"、"forms" , "sheets", "drivers", "ports", "windows", "lists", "heaps", "stacks", "applications", "exceptions"（除非它们是 Throwable）、"pins" 和 "buses"。

同样，任何合理的名词都是有用的如果它符合代码的业务规则并且是可以理解的。您可以执行以下任一操作：

Returns MapNode 条目的象限
Returns员工档案的平衡树

Answer 2

使用 "...(s)" 样式的复数标签，用 {@link} 到 class:

/**
  * Returns an {@link IdentityBank} of {@link Identity Identity(s)} with the given sex.
  */

这将呈现为：

Returns an IdentityBank of Identity(s) with the given sex.

读起来更容易、更自然，而且你说的很清楚。

无论如何，您应该为 class 使用 {@link}。它负责 <code> 样式格式，和为实际的 class.

提供 HTML link

您可以在 link 之后编码“(s)” ，即 {@link Identity}(s)，这意味着 {@link} 的完全常规用法, 但中间字会有字体变化:

Returns an IdentityBank of Identity(s) with the given sex.

恕我直言，这降低了清晰度并可能导致混淆。

Answer 3

^{看到题目就想：这个不是怎么像"Primarily opinion-based"一样5分钟后就关闭了？但我认为这是一个重要的问题，我为此苦恼了太多，最终得出的结论是可能存在不同（objective，即而不是基于意见！）不同选项的论点 - 这是我的两分钱：}

以class名称Customer和Identity为例，有不同的选项，将呈现如下：

All Customers have Identitys

使用不同字体的 "s" 会降低可读性。 "Identity" 的错误复数形式值得怀疑。
All Customers have Identities

乍一看这可能看起来不错。但它有一个严重的缺点：通常的做法是将 s 附加到 class 包含工厂方法的 class 名称！例如，按照惯例，包含 Customer 个对象的工厂方法的 class 将被称为 Customers。还有像这样的 JavaDoc...:[=33=]

You can create Customers with the methods in the Customers class

显然令人困惑：link 确实 而不是 导致您可能希望从您单击的名称中获得的文档。
我通常采用的解决方案（我在上面讲到方法2的缺点时已经使用过。）：

All Customer objects have Identity objects.

是的，这听起来可能有点不自然，但我认为这是最好的权衡：名称 Identity 是可读的，很明显它是一个 class 名称，并且class 的名字是 Identity 是明确的。

旁注：我通常将名称插入为 {@link ...}。由于 Eclipse 中的自动完成功能，这很方便，而且它可以显着简化对生成的 JavaDocs 的浏览。当 class 名称出现在文档块中时，我建议至少第一次使用 {@link ...}。对于进一步的出现，可以使用 <code>...</code>。

Answer 4

我通常更喜欢的第三个选项（即 {@link …} 和其他一些复数词，例如 "objects"），但有时使用 {@linkplain …} 也是一个不错的选择备选方案：

/**
 * Returns an {@link IdentityBank} of {@linkplain Identity identities} with the given sex.
 */

这将呈现如下内容：

Returns an IdentityBank of identities with the given sex.

这样你就知道有 some class 处理身份（你可以通过 link 找到哪个）但它是清楚（从所有小写拼写和格式）这不是 class 的确切名称，与逐字 IdentityBank.

形成对比

（注意：此示例可能不是此方法的最佳示例，但它演示了要点和用法。）

Answer 5

按照 https://developers.google.com/style/api-reference-comments 中的建议，我将使用以下内容：

/**
 * Returns an {@link IdentityBank} of {@link Identity} objects with the given sex.
 */

虽然有 {@link Identity identities} 语法的选项，但我不会使用它，因为这样做会冒 Identity 的重命名重构未被相应反映的风险。
更具体地说，如果您将 Identity 重命名为 Identification，您很可能会以 {@link Identification identities} 结束，而 identities 保持不变而不会引起注意。

在Javadocs中，我应该如何在<code>标签中写复数形式的单数对象？

In Javadocs, how should I write plural forms of singular Objects in <code> tags?

java

grammar

javadoc