Bonnes pratiques de documentation Java (Javadoc)

• Les membres publics et protégés doivent être documentés avec des commentaires Javadoc.
• Il est recommandé de documenter aussi les membres package-private et private, en particulier s'ils sont complexes ou ne sont pas auto-explicatifs.
• La première phrase du commentaire Javadoc est la description récapitulative. Elle doit être un aperçu concis de ce que fait la méthode et se terminer par un point.
• Utilisez @param pour les paramètres de méthode. La description commence par une lettre minuscule et ne se termine pas par un point.
• Utilisez @return pour les valeurs de retour des méthodes.
• Utilisez @throws ou @exception pour documenter les exceptions levées par les méthodes.
• Utilisez @see pour les références à d'autres types ou membres.
• Utilisez {@inheritDoc} pour hériter la documentation des classes de base ou interfaces.
  • À moins qu'il y ait un changement majeur de comportement, auquel cas vous devriez documenter les différences.
• Utilisez @param <T> pour les paramètres de type dans les types génériques ou les méthodes.
• Utilisez {@code} pour les extraits de code en ligne.
• Utilisez <pre>{@code ... }</pre> pour les blocs de code.
• Utilisez @since pour indiquer quand la fonctionnalité a été introduite (p. ex., numéro de version).
• Utilisez @version pour spécifier la version du membre.
• Utilisez @author pour spécifier l'auteur du code.
• Utilisez @deprecated pour marquer un membre comme obsolète et proposer une alternative.