Question

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.

Here is an example for clarity:

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

or

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

Answer 1

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

使用复数形式时，您可以使用短语＆＃34; X实例＆＃34;。所以使用你的例子，你可以把：

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

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

您应该避免在框架，系统或应用程序中使用与现有术语或类名冲突的术语，除非您使用的是已使用过的术语。例如，不要说＆＃34;返回案例文件列表＆＃34;除非您在文件系统中引用文字文件。使用它来引用文件的业务规则概念会增加混淆的可能性。其他要考虑避免的条款可能是＆＃34;数据库＆＃34;，＆＃34;表＆＃34; （除非引用数据库中的实际表格或它们的抽象或表示），＆＃34;页面＆＃34;，＆＃34;表格＆＃34;，＆＃34;表格＆＃34;，＆＃34;驱动程序＆＃34;，＆＃34; ports＆＃34;，＆＃34; windows＆＃34;，＆＃34; list＆＃34;，＆＃34; heaps＆＃34;，＆＃34; stacks＆＃34;，＆＃34;应用程序＆＃34;，＆＃34;例外＆＃34; （除非他们 Throwable ），＆＃34; pin＆＃34;，＆＃34; bus＆＃34;。

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

返回MapNode条目的象限

返回BalancedTree of Employee档案

Answer 2

使用＆＃34; ...（s）＆＃34;样式复数标签，类{@link}：

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

这将呈现为：

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

阅读起来既简单又自然，而且明显清楚你所说的内容。

无论如何，您应该使用{@link}进行课程。它负责<code>样式格式，和提供实际类的HTML链接。

你可以编码＆＃34;（s）＆＃34; 在链接之后，即{@link Identity}(s)，意味着{@link}的完全传统用法，但中间字词会有字体更改：

返回具有给定性别的IdentityBank Identity个。{/ p>

恕我直言会降低清晰度并导致混淆。

Answer 3

^{当我看到问题标题时，我想知道：这个不如何在5分钟之后被关闭为“主要基于意见”？但我认为这是一个重要的问题，而且我一直在为此苦恼太多，最终得出的结论是，可能存在不同的（客观的，即不基于意见的！）论点。不同的选择 - 所以这是我的两分钱：}

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

所有Customer都有Identity s

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

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

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

显然令人困惑：链接 not 导致您可能会从您点击的名称中获得的文档。
我经常使用的解决方案（我在上面讨论了方法2的缺点时已经使用过它）。

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

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

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

Answer 4

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

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

这将是这样的：

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

这样你知道有一些一些类来处理身份（你可以通过链接找到哪个）但是很明显（从全部小写拼写和格式化）这个与逐字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> tags?

5 个答案: