¿Cómo modifico el Javadoc cuando modifico el código de otra persona?

Question

Estoy trabajando en el código de otra persona y haciendo modificaciones importantes. (Lo estoy convirtiendo para utilizar una base de datos diferente a la que utilizó originalmente). ¿Cómo indico en los comentarios de Javadoc que no soy el autor original del código, pero que sí hice contribuciones al mismo? ¿Hay una manera limpia o estándar de hacer esto ya? Mi Google no me está ayudando a resolver esto.

Ejemplo:

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

Asimismo, no sé el nombre del autor original, por lo todo lo que puedo poner es a mí mismo. . .

Answer 1

Esos comentarios no pertenecen al javadoc :-) El javadoc debe explicar el contrato: es lo que se extrae y se muestra en la "documentación" generada automáticamente. El resto son solo comentarios normales o, quizás aún mejor en este caso, entradas de registro SCM y no tienen cabida en el javadoc.

que sería probable que deje el autor original, pero si quieres de crédito ...

... ver la referencia Javadoc @author y tenga en cuenta que puede incluirse en múltiples ocasiones. En esta sección se explicitly relates to multiple authors y pedidos, 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 { ... } 

feliz de codificación.

---

Notas sobre preguntas algo no relacionadas con el ejemplo en la publicación ... si no se conoce al autor, entonces se pueden hacer varias cosas. Ante todo agregue un enlace o referencia a donde se obtuvo la fuente original - también se puede anotar un "No escribí esto originalmente" para mayor claridad.

Luego, dependiendo de su preferencia:

1. No especifique un campo @author - ni siquiera a sí mismo. No es obligatorio.
2. Agregándose como el único autor; la fuente original se menciona anteriormente en el javadoc
3. Agregue un autor ficticio y usted como el segundo autor, p. @author Unknown@author unascribed (ver comentarios y @author).
4. Haga lo que quiera dentro de los términos de la licencia, si corresponde.

Answer 2

Puede tener más de una etiqueta @author. Por lo tanto, si ha realizado cambios extensos en una clase, solo agregue una nueva etiqueta @author con su propio nombre. No es necesario enumerar los cambios que ha realizado, el historial de revisión debería mostrarlo lo suficientemente bien.