В Javadocs, как я должен писать множественные формы особых объектов в <code> tags?

У меня есть класс с именем Identity. В моих комментариях 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.
  */

Ответ 1

Используйте ярлык стиля "... (s)" с {@link} для класса:

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

Это будет отображаться как:

Возвращает IdentityBank Identity(s) с данным сексом.

Легко и естественно читать, и понятно и понятно, что вы говорите.

В любом случае вы должны использовать {@link} для классов. Он заботится о форматировании стиля <code> и предоставляет ссылку HTML для фактического класса.

Вы можете закодировать "(ы)" после ссылки, т.е. {@link Identity}(s), что означает полностью обычное использование {@link}, но было бы среднее изменение шрифта:

Возвращает IdentityBank Identity с данным сексом.

который ИМХО уменьшает ясность и может вызвать путаницу.

Ответ 2

Похоже, вам нужно сделать две вещи: использовать хорошую грамматику, а также использовать литералы, дословные имена ваших классов, чтобы пользователи вашего javadoc могли искать их.

Одна вещь, которую вы можете сделать при работе с множественными числами, - это фраза "X-экземпляры". Поэтому, используя ваш пример, вы можете поставить:

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

Если вам нужно указать множественное число типа значения (которое не имеет экземпляров как таковое), вы можете использовать "значения X". Например, вы можете сказать: "Возвращает список значений int". Другими допустимыми именами могут быть "записи", "заметки", "записи", "уведомления" или, как упоминалось в @Marco13, "объекты".

Вам следует избегать использования терминов, которые сталкиваются с существующим термином искусства или именем класса в вашей структуре, системе или приложении, если вы не используете этот термин, поскольку он уже используется. Например, не говорите, что "возвращает список файлов Case", если вы не ссылаетесь на литеральные файлы в файловой системе. Использование его для обозначения концепции бизнес-правил файла добавляет потенциал для путаницы. Другими терминами, которые следует учитывать по этой причине, могут быть "базы данных", "таблицы" (если только они не относятся к фактическим таблицам в базе данных или абстракции или их представлению), "страницы", "формы", "листы", "драйверы", "порты", "окна", "списки", "кучи", "стеки", "приложения", "исключения" (если только они не выбрасываются), "контакты" и "шины".

Ответ 3

^{Когда я увидел заголовок вопроса, я задался вопросом: как этот не был закрыт через 5 минут как "в основном основанный на мнениях"? Но я думаю, что это важный вопрос, и я слишком много мучился из-за этого, в конце концов приходя к выводу, что могут быть разные (объективные, а не основанные на мнениях!) Аргументы для разных вариантов - так вот мои два цента:}

Используя имена классов Customer и Identity в качестве примеров, существуют различные параметры, которые будут отображаться следующим образом:

Все Customer имеют Identity s

Наличие "s" в другом шрифте снижает читаемость. Неправильное множественное число "Идентичность" сомнительно.
Все Customers имеют Identities

Это может показаться приятным с первого взгляда. Но у этого есть серьезный недостаток: распространенная практика заключается в добавлении s к именам классов для классов, которые содержат методы factory! Например, класс, который содержит методы factory для объектов Customer, условно будет называться Customers. И JavaDoc вроде этого...:

Вы можете создать Customers с помощью методов в Customers класс

явно запутывает: ссылка не приводит к документации, которую вы можете ожидать от имени, на которое вы нажимаете.
Решение, которое я обычно применяю (и я уже использовал его выше, когда говорил о недостатке подхода 2.):

Все Customer объекты Identity объекты.

Да, это может показаться немного неестественным, но я считаю это лучшим компромиссом: имя Identity читается, очевидно, что это имя класса, и недвусмысленно, что имя класса Identity.

Замечание: Обычно я вставляю имена как {@link ...}. Это удобно благодаря автозавершению в Eclipse и потому, что он может значительно упростить просмотр через результирующие JavaDocs. Я бы рекомендовал использовать {@link ...} как минимум в первый раз, когда имя класса появляется в блоке документации. Для дальнейшего появления можно использовать <code>...</code>.

Ответ 4

Я обычно предпочитаю третий вариант ответа Марко13 (т.е. {@link …} с некоторым другим множественным словом вроде "объектов" ), но иногда использование {@linkplain …} также хорошая альтернатива:

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

Это будет выглядеть примерно так:

Возвращает IdentityBank идентификаторы с данным сексом.

Таким образом, вы знаете, что существует некоторый класс, который обрабатывает тождества (и вы можете узнать, что, следуя ссылке), но ясно (из всего строчного написания и форматирования), что это не точное имя класс, в отличие от дословного IdentityBank.

(Примечание. Этот пример может быть не лучшим для этого метода, но он демонстрирует точку и использование.)