Details | Last modification | View Log | SVN | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 15 | arune | 1 | Comment all public and protected classes, fields & methods with JavaDoc! |
| 2 | |||
| 3 | Method/Function example: |
||
| 4 | |||
| 5 | /** |
||
| 6 | * Here goes the function description. Be short, but precise. |
||
| 7 | * Wrap the lines so things look nice. Don't forget to finish |
||
| 8 | * every sentence with a dot (or else, JavaDoc might fail). |
||
| 9 | * |
||
| 10 | * @param someString Here goes a description for the |
||
| 11 | * "someString"-parameter. Wrap the lines as usual, and don't |
||
| 12 | * forget to comment what a value of "null" means (if the |
||
| 13 | * parameter is an Object that is). |
||
| 14 | * |
||
| 15 | * @param someInt Here goes the description for the "someInt"- |
||
| 16 | * parameter. |
||
| 17 | * |
||
| 18 | * @return Describe what the function returns here. Don't |
||
| 19 | * write this like "@return This method returns...", but |
||
| 20 | * instead something like this "@return the sum of A and B". |
||
| 21 | */ |
||
| 22 | protected int myMethod(String someString, int someInt) { |
||
| 23 | this.someString = someString; |
||
| 24 | } |
||
| 25 | |||
| 26 | |||
| 27 | Class example: |
||
| 28 | |||
| 29 | /** |
||
| 30 | * Class description goes here. Same procedure as for method |
||
| 31 | * descriptions. |
||
| 32 | * |
||
| 33 | * @author [Your name goes here] (If an @author-tag already exists, |
||
| 34 | * just add another one with your name, indicating that you |
||
| 35 | * have also participated writing the class) |
||
| 36 | */ |
||
| 37 | class MyClass extends SomeOtherClass implements SomeInterfaces { |
||
| 38 | |||
| 39 | //this is a private field, so no need to JavaDoc it! |
||
| 40 | private int myInt; |
||
| 41 | |||
| 42 | /** |
||
| 43 | * This is a public or protected field, and thus, we must provide |
||
| 44 | * JavaDoc since somebody else might use this. Description |
||
| 45 | * of the field goes here. |
||
| 46 | */ |
||
| 47 | protected String myString; |
||
| 48 | |||
| 49 | //no need to JavaDoc this either. only if it would have |
||
| 50 | //been public or protected (in that case, use same format |
||
| 51 | //as for this outer class) |
||
| 52 | private class MyInnerClass { |
||
| 53 | |||
| 54 | //ok, now this is public, but the class it belongs to |
||
| 55 | //is just private, so no need to JavaDoc this either |
||
| 56 | //(we're the only ones who're going to be able to use |
||
| 57 | //this anyway) |
||
| 58 | public String blabla; |
||
| 59 | |||
| 60 | } |
||
| 61 | |||
| 62 | } |
||
| 63 | |||
| 64 | |||
| 65 | If you're overriding a method that already has good javadoc comments |
||
| 66 | you don't need to provide new javadoc comments if you don't want to. |
||
| 67 | Javadoc tools will then use the comments from the method in the |
||
| 68 | superclass instead. Here is an example: |
||
| 69 | |||
| 70 | This superclass has proper Javadoc comments already: |
||
| 71 | |||
| 72 | abstract class Module { |
||
| 73 | /** |
||
| 74 | * Gets the name of the module. |
||
| 75 | * @return The name of the module. |
||
| 76 | */ |
||
| 77 | abstract public String getName(); |
||
| 78 | } |
||
| 79 | |||
| 80 | |||
| 81 | And thus, this inheriting class doesn't need to provide its own |
||
| 82 | Javadoc comments for the functions it overrides: |
||
| 83 | |||
| 84 | class MyModule extends Module { |
||
| 85 | public String getName() { |
||
| 86 | return "MyModule"; |
||
| 87 | } |
||
| 88 | } |