Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

Tags:

java

javadoc

People also ask

How do I automatically add Javadoc?

In the Package Explorer view, select a Java project and click Project > Generate Javadoc with Diagrams > Automatically. In the Generate Javadoc wizard, under Javadoc command, select the Javadoc command (an executable file). Note: Only Oracle JDK Version 1.4.

What does @SEE mean in Javadoc?

We can use the @see and @link tag multiple times in a class, package, or method. The @see tag declares references that point to an external link, class, or method. The @link tag can also be used multiple times for declaring inline links or in contrast with other block tags.

What is the purpose of having Javadoc specific comments within code?

The javadoc Tags Adds the author of a class. Displays text in code font without interpreting the text as HTML markup or nested javadoc tags. Represents the relative path to the generated document's root directory from any generated page. Adds a comment indicating that this API should no longer be used.


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.

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.