在Javadocs中，我应该如何在<code>标签中编写复数forms的单数对象？
我有一个名为Identity的类。 在我的javadoc评论中，我把它作为一个复数。 我可以想到两个解决scheme：将引用更改为<code>Identities</code>或<code>Identity</code> 。 这些都没有感觉是正确的，我想知道是否有更好的解决scheme。
这是一个清晰的例子：
/** * 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. */
使用“…（s）”风格的复数标签， {@link}给class级：
/** * Returns an {@link IdentityBank} of {@link Identity Identity(s)} with the given sex. */
这将呈现为：
返回给定性别的
IdentityBank的Identity(s)。
阅读起来很容易，也很自然，明显，清楚你在说什么。
无论如何，您应该使用{@link}进行授课。 它负责<code>风格的格式化， 并提供一个到实际类的HTML链接。
您可以在链接之后对“（s）” 进行编码，即{@link Identity}(s) ，意思是{@link}的完全常规用法，但中间字将会有字体变化：
返回给定性别的
IdentityBank的Identity。
恕我直言，降低清晰度，可能会导致混乱。
听起来有两件事情你想要做：使用良好的语法，但也使用你的类的文字，逐字的名称，使您的javadoc用户可能会查找他们。
使用复数forms你可以做的一件事是使用短语“X实例”。 所以用你的例子，你可以把：
/** * Returns an <code>IdentityBank</code> of <code>Identity</code> instances with the given sex. */
如果您需要指定复数的值types（本身没有实例），则可以使用“X值”。 例如，你可以说“返回一个int值列表”。 其他可接受的名称可能是“logging”，“注释”，“条目”，“通知”，或者如提到的“对象”。
您应该避免使用在您的框架，系统或应用程序中与艺术或类名称的现有术语相冲突的术语，除非您正在使用已经使用过的术语。 例如，除非你指的是文件系统中的文字文件，否则不要说“返回一个Case文件列表”。 使用它来引用文件的业务规则概念增加了混淆的可能性。 由于这个原因，要考虑避免的其他术语可以是“数据库”，“表格”（除非参考数据库中的实际表格或其抽象或表示），“页面”，“表格”，“表格”，“驱动程序” ，“端口”，“窗口”，“列表”，“堆”，“堆栈”，“应用程序”，“例外”（除非是Throwable ），“引脚”和“总线”。
当我看到问题标题的时候，我想知道：5分钟之后，这怎么可能没有被closures为“主要以观点为基础”呢？ 但是我认为这是一个重要的问题，而且我一直在为这个问题烦恼太多，最终得出结论：对于不同的select可能会有不同的（客观的，即不是基于观点的）论据 – 所以这里是我的两分钱：
使用类名称Customer和Identity作为示例，有不同的选项，它们将呈现如下：
-
所有
Customer都有Identity使用不同字体的“s”会降低可读性。 “身份”的错误复数是有问题的。
-
所有
Customers都有Identities乍一看，这可能看起来不错。 但是它有一个严重的缺点：对于包含工厂方法的类来说，追加类名是一种常见的做法！ 例如，一个包含
Customer对象的工厂方法的类按照惯例将被称为Customers。 和这样的JavaDoc …：您可以使用
Customers类中的方法创buildCustomers显然是令人困惑的：链接不会导致您可能期望从您点击的名称的文档。
-
我通常使用的解决scheme（在谈论方法2的缺点时，我已经在上面使用了它）：
所有
Customer对象都有Identity对象。是的，这可能听起来有点不自然，但我认为这是最好的权衡：
Identity的名称是可读的，显然它是一个类名，而且类的名称是Identity是不明智的。
附注：我通常将名称插入{@link ...} 。 这很方便，因为在Eclipse中自动完成，因为它可以显着简化浏览JavaDocs。 当文档块中出现类名时，我build议至less第一次使用{@link ...} 。 为了进一步显示，可以使用<code>...</code> 。
我通常更喜欢Marco13s答案的第三个选项（即{@link …}和其他一些复数词，比如“objects”），但有时使用{@linkplain …}也是一个好的select：
/** * Returns an {@link IdentityBank} of {@linkplain Identity identities} with the given sex. */
这将会是这样的：
返回给定性别
IdentityBank的身份库 。
这样你就知道有一些类处理身份（你可以通过下面的链接find它），但是很明显（从全部小写拼写和格式），这不是类的确切名称，与逐字的IdentityBank形成对比。
（注意：这个例子对于这个方法可能不是最好的，但是它certificate了这一点和用法。）
