Details | Last modification | View Log | SVN | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 15 | arune | 1 | <html> |
| 2 | |||
| 3 | <head> |
||
| 4 | <title>JavaDoc guidelines</title> |
||
| 5 | <link rel="StyleSheet" href="doc.style.css" type="Text/CSS"> |
||
| 6 | </head> |
||
| 7 | |||
| 8 | <body> |
||
| 9 | |||
| 10 | <h1>JavaDoc guidelines</h1> |
||
| 11 | <p>You should always comment your code thoroughly, or else others will have a hard time reading and/or using |
||
| 12 | your code. Here are some basic guidelines on how to write proper JavaDoc comments.</p> |
||
| 13 | |||
| 14 | <h2>Methods</h2> |
||
| 15 | <p>When writing JavaDoc for methods, always provide descriptions for the actual <span class="mark_red">method</span>, |
||
| 16 | all the <span class="mark_red">parameters</span> and also the <span class="mark_red">return value</span>. |
||
| 17 | Here is a short example:</p> |
||
| 18 | <pre> |
||
| 19 | /** |
||
| 20 | * Here goes the function description. Be short, but precise. |
||
| 21 | * Wrap the lines so things look nice. Don't forget to finish |
||
| 22 | * every sentence with a dot (or else, JavaDoc tools might fail). |
||
| 23 | * |
||
| 24 | * @param someString Here goes a description for the |
||
| 25 | * "someString"-parameter. Wrap the lines as usual, and don't |
||
| 26 | * forget to comment what a value of "null" means (if the |
||
| 27 | * parameter is an Object that is). |
||
| 28 | * |
||
| 29 | * @param someInt Here goes the description for the "someInt"- |
||
| 30 | * parameter. |
||
| 31 | * |
||
| 32 | * @return Describe what the function returns here. Don't |
||
| 33 | * write this like "@return This method returns...", but |
||
| 34 | * instead something like this "@return the sum of A and B". |
||
| 35 | */ |
||
| 36 | protected int myMethod(String someString, int someInt) { |
||
| 37 | this.someString = someString; |
||
| 38 | } |
||
| 39 | </pre> |
||
| 40 | |||
| 41 | <h2>Classes</h2> |
||
| 42 | <p>You should always comment your actual classes, but you also need to keep in mind |
||
| 43 | that, within your class, <span class="mark_red">all public and protected fields and/or methods should have |
||
| 44 | proper JavaDoc comments</span> as well. The basic rule is to think about whether or not |
||
| 45 | anybody else might be using the function/field you're creating. If it is |
||
| 46 | declared private, you're the only one that will ever use it, so it's OK to provide |
||
| 47 | some basic comment, like:</p> |
||
| 48 | <pre> |
||
| 49 | //counts the number of sent packets |
||
| 50 | private int packetCounter; |
||
| 51 | </pre> |
||
| 52 | <p>However, if it is declared public of protected, you need to provide JavaDoc-compatible |
||
| 53 | comments, much like the method-example above. A field would then look like this instead:</p> |
||
| 54 | <pre> |
||
| 55 | /** |
||
| 56 | * Counts the number of sent packets. |
||
| 57 | */ |
||
| 58 | public int packetCounter; |
||
| 59 | </pre> |
||
| 60 | <p>There is a special case though, if your field is protected or public inside a private inner |
||
| 61 | class, then nobody else will be able to use the inner class anyway, so you don't have to |
||
| 62 | that strict when writing inner classes. Simple comments will do. Now, here is a class example:</p> |
||
| 63 | <pre> |
||
| 64 | /** |
||
| 65 | * Class description goes here. Same procedure as for method |
||
| 66 | * descriptions. |
||
| 67 | * |
||
| 68 | * @author [Your name goes here] (If an @author-tag already exists, |
||
| 69 | * just add another one with your name, indicating that you |
||
| 70 | * have also participated writing the class) |
||
| 71 | */ |
||
| 72 | class MyClass extends SomeOtherClass implements SomeInterfaces { |
||
| 73 | |||
| 74 | //this is a private field, so no need to JavaDoc it! |
||
| 75 | private int myInt; |
||
| 76 | |||
| 77 | /** |
||
| 78 | * This is a public or protected field, and thus, we must provide |
||
| 79 | * JavaDoc since somebody else might use this. Description |
||
| 80 | * of the field goes here. |
||
| 81 | */ |
||
| 82 | protected String myString; |
||
| 83 | |||
| 84 | //no need to JavaDoc this either. only if it would have |
||
| 85 | //been public or protected (in that case, use same format |
||
| 86 | //as for this outer class) |
||
| 87 | private class MyInnerClass { |
||
| 88 | |||
| 89 | //ok, now this is public, but the inner class it belongs to |
||
| 90 | //is just private, so no need to JavaDoc this either |
||
| 91 | //(we're the only ones who're going to be able to use |
||
| 92 | //this anyway) |
||
| 93 | public String blabla; |
||
| 94 | |||
| 95 | } |
||
| 96 | |||
| 97 | } |
||
| 98 | </pre> |
||
| 99 | <p><span class="mark_red">If you're overriding a method that already has good JavaDoc comments you don't need to |
||
| 100 | provide new JavaDoc comments if you don't want to</span>. Only if you change the actual meaning |
||
| 101 | of the method will you have to provide new comments. However, if you're just modifying the |
||
| 102 | original method slightly, don't provide any comments at all. The JavaDoc tools will then use |
||
| 103 | the comments from the method in the superclass instead. Here is an example:</p> |
||
| 104 | <p>This superclass has proper JavaDoc comments for its methods already:</p> |
||
| 105 | <pre> |
||
| 106 | abstract class Module { |
||
| 107 | /** |
||
| 108 | * Gets the name of the module. |
||
| 109 | * @return The name of the module. |
||
| 110 | */ |
||
| 111 | abstract public String getName(); |
||
| 112 | } |
||
| 113 | </pre> |
||
| 114 | <p>And thus, an inheriting class doesn't need to provide its own JavaDoc comments for |
||
| 115 | the methods it overrides:</p> |
||
| 116 | <pre> |
||
| 117 | class MyModule extends Module { |
||
| 118 | public String getName() { |
||
| 119 | return "MyModule"; |
||
| 120 | } |
||
| 121 | } |
||
| 122 | </pre> |
||
| 123 | |||
| 124 | </body> |
||
| 125 | </html> |