How do I modify the Javadoc when I modify someone else's code?

Question

I am working on someone else's code and making significant modifications. (I am converting it to use a different database than the one he originally used.) How do I indicate in the Javadoc comments that I am not the original author of the code, but that I did make contributions to it. Is there a clean or standard way of doing this already? My Googling is not helping me figure this out.

Example:

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

I also don't know the original author's name, so all I can put down is myself . . .

Answer 1

Those comments do not belong in the javadoc :-) The javadoc should explain the contract -- it is what is extracted and displayed in the auto-generated "documentation". The rest are just normal comments or, perhaps better yet in this case, SCM log entries and have no place in the javadoc!

I would likely just leave the original author, but if you want credit...

...see the @author javadoc reference and note that it can be included multiple times. This section explicitly relates to multiple authors and ordering, 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 { ... }

Happy coding.

---

Notes on question somewhat unrelated to example in post... if the author isn't known, then several things can be done. First and foremost add a link or reference to where the original source was obtained -- an optional "I didn't write this originally" for clarity can be noted as well.

Then, depending upon your preference:

1. Don't specify an @author field -- not even yourself. It's not required.
2. Add yourself as the sole author; the original source is mentioned above in the javadoc
3. Add a dummy author and yourself as the second author, e.g. @author Unknown @author unascribed (see comments and @author).
4. Do whatever you want within terms of the license, if any.

Answer 2

You can have more than one @author tag. So, if you've made extensive changes to a class, just add a new @author tag with your own name in it. There's no need to list the changes you've done---the revision history should show that well enough.