WebSVN – HomeAutomation – Diff – /branches/modules/PcSoftware/MacBeth/Docs/JavaDocGuide.txt


Comment all public and protected classes, fields & methods with JavaDoc!
 
Method/Function example:
 
/**
 * Here goes the function description. Be short, but precise.
 * Wrap the lines so things look nice. Don't forget to finish
 * every sentence with a dot (or else, JavaDoc might fail).
 *
 * @param someString Here goes a description for the
 * "someString"-parameter. Wrap the lines as usual, and don't
 * forget to comment what a value of "null" means (if the
 * parameter is an Object that is).
 *
 * @param someInt Here goes the description for the "someInt"-
 * parameter.
 *
 * @return Describe what the function returns here. Don't
 * write this like "@return This method returns...", but
 * instead something like this "@return the sum of A and B".
 */
protected int myMethod(String someString, int someInt) {
    this.someString = someString;
}
 
 
Class example:
 
/**
 * Class description goes here. Same procedure as for method
 * descriptions.
 *
 * @author [Your name goes here] (If an @author-tag already exists,
 * just add another one with your name, indicating that you
 * have also participated writing the class)
 */
class MyClass extends SomeOtherClass implements SomeInterfaces {
    
    //this is a private field, so no need to JavaDoc it!
    private int myInt;
    
    /**
     * This is a public or protected field, and thus, we must provide
     * JavaDoc since somebody else might use this. Description
     * of the field goes here.
     */
    protected String myString;
    
    //no need to JavaDoc this either. only if it would have
    //been public or protected (in that case, use same format
    //as for this outer class)
    private class MyInnerClass {
        
        //ok, now this is public, but the class it belongs to
        //is just private, so no need to JavaDoc this either
        //(we're the only ones who're going to be able to use
        //this anyway)
        public String blabla;
        
    }
    
}
 
 
If you're overriding a method that already has good javadoc comments
you don't need to provide new javadoc comments if you don't want to.
Javadoc tools will then use the comments from the method in the
superclass instead. Here is an example:
 
This superclass has proper Javadoc comments already:
 
abstract class Module {
    /**
     * Gets the name of the module.
     * @return The name of the module.
     */
    abstract public String getName();
}
 
 
And thus, this inheriting class doesn't need to provide its own
Javadoc comments for the functions it overrides:
 
class MyModule extends Module {
    public String getName() {
        return "MyModule";
    }
}

Subversion Repositories HomeAutomation

(root)/branches/modules/PcSoftware/MacBeth/Docs/JavaDocGuide.txt – Rev 641 → 800

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