Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: change JavaDoc guildelines so that JavaDoc is not required for every element

...

All files should contain descriptive comments in Javadoc™ form so that documentation can be generated automatically. Of course, additional non-Javadoc source code comments should appear as appropriate.

  1. All classes and methods Classes, methods and fields should have a block comment describing them if it makes sense. There is no need to add comments merely for the sake of commenting. For example, it is not necessary to add a comment for a method if the comment does not provide more information than the signature and the method name already do.

  2. JavaDoc comments must not be copied from methods that are being overriden. If the comment from the method that you are overriding is sufficient, you do not need to provide JavaDoc for the newly added method - JavaDoc will automatically copy the JavaDoc from the overriden method. If you want to extend the comment from the overriden method with new information, use {@inheritDoc} to copythe copy the comment from the superclass and add your text.

  3. All JavaDoc for methods contain contains a short description of their arguments (using @param), the return value (using @return) and the exceptions they may throw (using @throws).

  4. Each class should include @see and @link references as appropriate.