Dans Javadocs, comment écrire des formes plurielles d'Objets singuliers dans les balises?

Il semble qu'il y ait deux choses que vous voulez faire ici: utiliser une bonne grammaire mais aussi utiliser les noms littéraux et verbatim de vos classes afin que les utilisateurs de votre javadoc puissent les rechercher.

Une chose que vous pouvez faire lorsque vous travaillez avec les pluriels est d'utiliser l'expression "X instances". Donc, en utilisant votre exemple, vous pouvez mettre:

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

Si vous devez spécifier un pluriel d'un type de valeur (qui n'a pas d'instances en soi), vous pouvez utiliser "X values". Par exemple, vous pouvez dire " Renvoie une liste de int valeur". D'autres noms acceptables pourrait être "dossiers", "notes", "entrées", "avis", ou, comme @Marco13 mentionné, "objets".

Vous devez éviter d'utiliser des termes qui entrent en collision avec un terme d'art ou un nom de classe existant dans votre framework, système ou application, sauf si vous utilisez ce terme tel qu'il est déjà utilisé. Par exemple, ne dites pas "renvoie une liste de fichiers de cas" sauf si vous faites référence à des fichiers littéraux dans un système de fichiers. De l'utiliser pour faire référence à un business rules concept d'un fichier ajoute le risque de confusion. D'autres termes à éviter pour cette raison peuvent être "bases de données", "tables" (sauf s'il s'agit de tables réelles dans une base de données ou d'une abstraction ou d'une représentation de celles-ci), "pages", "formulaires", "feuilles", "pilotes", "ports", "fenêtres", "listes", "tas", "piles", "applications", "exceptions" (sauf si elles sont Throwable), "pins" et "bus".

De même, tout nom raisonnable est utile s'il correspond aux règles commerciales du code et est compréhensible. Vous pouvez effectuer l'une des opérations suivantes:

• Renvoie un quadrant d'entrées MapNode
• Renvoie un BalancedTree de dossiers d'employés

^{Quand j'ai vu le titre de la question, je me suis demandé: Comment ce pas a-t-il été fermé après 5 minutes comme "Principalement basé sur l'opinion"? Mais je pense que c'est une question importante, et j'agonise beaucoup trop à ce sujet, pour finalement arriver à la conclusion qu'il peut y avoir différents (objectifs, c'est-à-dire pas basés sur l'opinion! arguments pour les différentes options - voici donc mes deux cents:}

En utilisant les noms de classe Customer et Identity comme exemples, il y a différentes options, qui seraient rendues comme suit:

1. Tous Customers ont Identitys

   Avoir le "s" dans une police différente diminue la lisibilité. Le mauvais pluriel de "Identité" est discutable.

2. Tous Customers ont Identities

   Cela peut sembler agréable à première vue. Mais il a un grave inconvénient: Il est courant d'ajouter un s aux noms de classe pour classes qui contiennent des méthodes d'usine! Par exemple, une classe qui contient des méthodes d'usine pour Customer objets serait, par convention, appelé Customers. Et un JavaDoc comme ça...:

   , Vous pouvez créer Customers avec les méthodes de la Customers de catégorie

   Est clairement déroutant: Le lien ne pas mène à la documentation que vous pourriez attendre du nom sur lequel vous cliquez.

3. La solution que j'applique habituellement (et je l'ai déjà utilisé ci-dessus, en parlant de l'inconvénient de l'approche 2.) :

   Tous Customer les objets ont Identity objets.

   Oui, c'est un peu contre nature, mais je le considère comme le meilleur compromis: Le nom Identity il est lisible, il est évident que c'est un nom de classe, et il est unambigous que le nom de la classe est Identity.

Une note de côté: J'insère généralement les noms comme {@link ...}. C'est pratique en raison de l'auto-complétion dans Eclipse, et parce qu'il peut considérablement simplifier la navigation à travers les JavaDocs résultants. Je recommanderais d'utiliser {@link ...} au moins la première fois lorsqu'un nom de classe apparaît dans un bloc de documentation. Pour d'autres comparutions, <code>...</code> peut être utilisé.

Je préfère généralement la troisième option de réponse Marco13s (c'est-à-dire {@link …} avec un autre mot pluriel comme "objets") mais parfois l'utilisation de {@linkplain …} est également une bonne alternative:

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

Ce serait rendu quelque chose comme ceci:

Renvoie un IdentityBank de identités avec le sexe.

De cette façon, vous savez qu'il existe une classe qui gère les identités (et vous pouvez savoir laquelle en suivant le lien) mais c'est clair (à partir de l'orthographe et de la mise en forme toutes les minuscules) que ce n'est pas le nom exact de la classe, contrairement au verbatim IdentityBank.

(Remarque: Cet exemple n'est peut-être pas le meilleur pour cette méthode mais il démontre le point et l'utilisation.)