web-dev-qa-db-fra.com

Comment puis-je modifier Javadoc lorsque je modifierai le code de quelqu'un d'autre?

Je travaille sur le code de quelqu'un d'autre et je fais des modifications importantes. (Je la convertissez-moi pour utiliser une base de données différente de celle utilisée à l'origine.) Comment puis-je indiquer dans les commentaires Javadoc que je ne suis pas l'auteur original du code, mais que j'ai commis des contributions. Y a-t-il un moyen propre ou standard de faire cela déjà? Mon googling n'aide pas à moi comprendre ceci.

Exemple:

/**
* This class does some really awesome stuff.
* 
* @author Steph the Great - Modified to use PostgreSQL instead of Derby;
*         added comments to the code
*/

Je ne connais pas non plus le nom de l'auteur d'origine, alors tout ce que je peux poser est moi-même. . .

javajavadoc
33
Steph

Ces commentaires ne appartiennent pas dans le javadoc :-) Le javadoc devrait expliquer le contrat - il est ce qui est extrait et affiché dans la " documentation " générée automatiquement. Les autres ne sont que des commentaires normaux ou, peut-être mieux encore dans ce cas, SCM BOG entrées et n'ont aucune place dans le Javadoc!

Je voudrais probablement juste quitter l'auteur d'origine, mais si vous voulez du crédit ...

... Voir le @ Auteur Référence Javadoc et note qu'il peut être inclus plusieurs fois. Cette section concerne explicitement plusieurs auteurs et commande, etc.

/**
* This class does some really awesome stuff.
* It uses PostreSQL. 
*
* @author Steph the Great
* @author Freddy Four Fingers
*/
// DEC2012 - Fred - Modified to use PostgreSQL instead of Derby (but really, use SCM!)
class Awesome { ... }

Codage heureux.

Notes sur la question quelque peu sans rapport avec l'exemple de la poste ... Si l'auteur n'est pas connu, plusieurs choses peuvent être faites. Tout d'abord ajouter un lien ou une référence à l'endroit où a été obtenu la source d'origine - une option " Je n'ai pas écrit cette origine " pour plus de clarté peut noter aussi.

Ensuite, en fonction de votre préférence:

  1. Ne spécifiez pas un @author champ - pas même vous-même. Il est pas nécessaire.
  2. Ajoutez-vous comme le seul auteur; La source originale est mentionnée ci-dessus dans le Javadoc
  3. Ajouter un auteur mannequin et vous-même comme deuxième auteur, par exemple @author Unknown@author unascribed (voir Commentaires et @ Auteur ).
  4. Faites ce que vous voulez dans les termes de la licence, le cas échéant.
34
user166390

Vous pouvez avoir plus d'un @author étiqueter. Donc, si vous avez apporté de nombreux changements dans une classe, ajoutez simplement un nouveau @author tag avec votre propre nom dedans. Il n'est pas nécessaire d'énumérer les modifications que vous avez faites --- L'historique de révision doit indiquer que suffisamment bien.

11
Chris Jester-Young