La Documentation Java - @return et @param
Je me demande comment code de document avec @return et @param ...? Je suis une sorte de deviner que je ferais quelque chose comme
@return(whatever the method is returning)
@param(parameters that the method is taking in)
Aurais-je mettre des descriptions plus par la suite? Aussi, est-il quelque chose comme trop de documentation?
Vous devez vous connecter pour publier un commentaire.
La Javadoc guide de style explique l'utilisation de ces balises. @param décrit un paramètre et @return décrit la valeur de retour. (Il y a plusieurs autres balises.)
Rappelez-vous que Javadoc permet de générer la documentation de votre code, pas juste de vos commentaires. La signature de la méthode apparaît dans la sortie -- donc, ne pas dire au lecteur qu'il sait déjà. Le but de votre documentation est de fournir le plus d'informations sémantiques qui ne sont pas exprimées dans la signature. C'est qu'un paramètre numérique limitée à une plage spécifique de valeurs? Sont des valeurs de retour (comme null)? Document du contrat.
Vous demandez si il ya une telle chose comme trop de documentation. Oui, il est. Référence de l'API de la documentation qui est le plus utile lorsqu'il indique au lecteur tout et seulement ce qu'il doit savoir pour bien utiliser l'interface. Afin de documenter le contrat, mais ne rien dire buter comment votre code implémente cette interface. Lien vers d'autres éléments de l'API (comme d'autres interfaces ou des classes) si elles portent sur la partie que vous souhaitez documenter (par exemple si quelqu'un a besoin d'utiliser SomeFactory pour obtenir une instance de quelque Chose, la classe que vous filmez).
Ce n'est pas à dire que vous ne devriez jamais écrire quoi que ce soit de plus que quelques phrases; parfois, une interface est complexe et nécessite plus d'explications. De se demander si cette explication qui appartient à un package de présentation, le haut de la documentation au niveau d'une classe ou d'une interface, ou un membre en particulier. Si vous trouvez vous-même le découpage et le collage d'une explication en plusieurs endroits, ce qui peut être un signe que vous avez besoin pour répondre à un niveau supérieur à la place.
Ces choses sont des balises javadoc. La référence complète de la façon de les utiliser, ils vous pouvez les trouver ici: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
Mais un exemple de base pour ces deux vous avez mentionné ci-dessus ressemble à ceci:
Documentation javadoc sont toujours utilisés avant la méthode ou variable, ou de classe /interface
Pourquoi ne pas commencer par regarder ce que la documentation Javadoc sont?
http://en.wikipedia.org/wiki/Javadoc
Un exemple de la façon dont ils sont utilisés, c'est comme cela.
C'est Javadoc vous parlez:
La javadoc de l'outil (et les cibles qui utilisent cet outil dans divers systèmes de construction tels que gradle et maven) permettra de générer des fichiers HTML à partir de cela.
Avant, en fait, qu'une convention. Et seulement si vous le jugez nécessaire.
Oui.