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

I have a class named Identity. In my javadoc comments I am referencing it as a plural. I can think of two solutions: change the reference to <code>Identities</code> or <code>Identity</code>s. Neither of these feel correct, and I'm wondering if there's a better solution.

我有一个名为Identity的类。在我的javadoc评论中，我将其称为复数形式。我可以想到两个解决方案：更改Identities 或 Identity 的引用。这些都不正确，我想知道是否有更好的解决方案。

Here is an example for clarity:

这是一个清晰的例子：

/**
  * 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.
  */

4 个解决方案

#1

Use a "...(s)" style plural label, with a {@link} to the class:

使用“...（s）”样式复数标签，并在课程中使用{@link}：

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

This will render as:

这将呈现为：

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

返回具有给定性别的Identity的IdentityBank。

It's easy and more natural to read, and obvious and clear what you are saying.

阅读起来既简单又自然，而且显而易见，清晰明白。

You should be using {@link} anyway for classes. It takes care of <code> style formatting, and provides an HTML link to the actual class.

无论如何你应该使用{@link}来上课。它负责样式格式，并提供实际类的HTML链接。

You could code the "(s)" after the link, ie {@link Identity}(s), meaning a completely conventional usage of {@link}, but there would be a font change mid-word:

您可以在链接后编码“（s）”，即{@link Identity}（s），这意味着{@link}的完全传统用法，但是中间字体会有字体更改：

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

返回具有给定性别的Identity的IdentityBank。

which IMHO reduces clarity and could cause confusion.

恕我直言会降低清晰度并可能引起混淆。

#2

It sounds like there are two things you want to do here: use good grammar but also use the literal, verbatim names of your classes so that users of your javadoc may look them up.

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

One thing you can do when working with plurals is use the phrase "X instances". So using your example, you could put:

使用复数时可以做的一件事是使用短语“X实例”。所以使用你的例子，你可以把：

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

If you need to specify a plural of a value type (which doesn't have instances per se), you can use "X values". For example, you could say "Returns a list of int values". Other acceptable names might be "records", "notes", "entries", "notices", or, as @Marco13 mentioned, "objects".

如果需要指定多个值类型（本身没有实例），则可以使用“X值”。例如，您可以说“返回int值列表”。其他可接受的名称可能是“记录”，“注释”，“条目”，“通知”，或者如@ Marco13所述，“对象”。

You should avoid using terms that collide with an existing term of art or class name in your framework, system, or application unless you are using that term as it is already used. For example, do not say "returns a list of Case files" unless you are referring to literal files in a filesystem. Using it to refer to a business rules concept of a file adds potential for confusion. Other terms to consider avoiding for this reason may be "databases", "tables" (unless referring to actual tables in a database or an abstraction or representation of them), "pages", "forms", "sheets", "drivers", "ports", "windows", "lists", "heaps", "stacks", "applications", "exceptions" (unless they are Throwable), "pins", and "buses".

您应该避免在框架，系统或应用程序中使用与现有术语或类名冲突的术语，除非您使用的术语已经使用过。例如，除非您在文件系统中引用文字文件，否则不要说“返回案例文件列表”。使用它来引用文件的业务规则概念会增加混淆的可能性。因此而考虑避免的其他术语可能是“数据库”，“表”（除非引用数据库中的实际表或它们的抽象或表示），“页面”，“表单”，“表单”，“驱动程序” ，“端口”，“窗口”，“列表”，“堆”，“堆栈”，“应用程序”，“例外”（除非它们是可投掷的），“引脚”和“总线”。

Similarly, any reasonable noun at all is useful if it fits the business rules of the code and is understandable. You could do any of the following:

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

Returns a Quadrant of MapNode entries
返回MapNode条目的象限
Returns a BalancedTree of Employee dossiers
返回BalancedTree的Employee档案

#3

^{When I saw the question title, I wondered: How can this not have been closed after 5 minutes as "Primarily opinion-based"? But I think it is an important question, and I've been agonizing over this far too much, eventually coming to the conclusion that there may be different (objective, i.e. not opinion-based!) arguments for the different options - so here are my two cents:}

当我看到问题标题时，我想知道：在5分钟之后这怎么可能没有被关闭为“主要基于意见”？但我认为这是一个重要的问题，我一直在为这个问题苦苦挣扎，最终得出的结论是，对于不同的选项可能存在不同的（客观的，即不是基于意见的！）论据 - 所以这里是我的两分钱：

Using the class names Customer and Identity as examples, there are different options, which would be rendered as follows:

使用类名称Customer和Identity作为示例，有不同的选项，它们将呈现如下：

All Customers have Identitys

所有客户都有身份

Having the "s" in a different font decreases readability. The wrong plural of "Identity" is questionable.

使用不同字体的“s”会降低可读性。错误的复数“身份”是值得怀疑的。
All Customers have Identities

所有客户都有身份

This may look nice at the first glance. But it has a severe drawback: It is a common practice to append an s to class names for classes that contain factory methods! For example, a class that contains factory methods for Customer objects would, by convention, be called Customers. And a JavaDoc like this...:

乍一看，这看起来很不错。但它有一个严重的缺点：对于包含工厂方法的类，将s附加到类名是一种常见的做法！例如，按惯例，包含Customer对象的工厂方法的类将称为Customers。像这样的JavaDoc ......：

You can create Customers with the methods in the Customers class

您可以使用Customers类中的方法创建Customers

is plainly confusing: The link does not lead to the documentation that you might expect from the name that you are clicking on.

显然令人困惑：该链接不会导致您可能从您点击的名称中获得的文档。
The solution that I usually apply (and I already used it above, when talking about the drawback of approach 2.) :

我通常应用的解决方案（我在上面讨论了方法2的缺点时使用过它）：

All Customer objects have Identity objects.

所有Customer对象都具有Identity对象。

Yes, it may sound a bit unnatural, but I consider it as the best trade-off: The name Identity is readable, it is obvious that it is a class name, and it is unambigous that the name of the class is Identity.

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

A side note: I usually insert the names as {@link ...}. This is convenient due to the auto-completion in Eclipse, and because it can significantly simplify browsing through the resulting JavaDocs. I'd recommend to use {@link ...} at least the first time when a class name appears in a documentation block. For further appearances, <code>...</code> may be used.

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

#4

I usually prefer the third option of Marco13s answer (i.e. {@link …} with some other plural word like "objects") but sometimes the use of {@linkplain …} is also a good alternative:

我通常更喜欢Marco13s答案的第三个选项（即{@link ...}和其他复数词如“objects”）但有时使用{@linkplain ...}也是一个不错的选择：

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

This would be rendered something like this:

这将呈现如下：

Returns an IdentityBank of identities with the given sex.

返回具有给定性别的身份的IdentityBank。

This way you know that there is some class that handles identities (and you can find out which by following the link) but it is clear (from the all lowercase spelling and the formatting) that this is not the exact name of the class, in contrast to the verbatim IdentityBank.

这种方式你知道有一些类处理身份（你可以通过链接找到哪个），但很明显（从全部小写拼写和格式化），这不是类的确切名称，在与逐字的IdentityBank形成对比。

(Note: This example may not be the best for this method but it demonstrates the point and usage.)

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

#1