Skip to content

Commit a9a7bd2

Browse files
DaySDayS
committed
Merge pull request androidannotations#814 from excilys/765_javadoc
Improve javadoc for root annotations
2 parents 3aabc48 + edcd136 commit a9a7bd2

94 files changed

Lines changed: 2717 additions & 433 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/AfterInject.java‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,35 @@
2222

2323
/**
2424
* Methods annotated with @{@link AfterInject} will be called after the
25-
* constructor is called in an enhanced class.
25+
* constructor is called in an enhanced class. Any code depending on injected
26+
* fields should be done in an {@link AfterInject} annotated method.
27+
* <p/>
28+
* The method MUST have zero parameters.
29+
* <p/>
30+
* There MAY be several methods annotated with @{@link AfterInject} in the same
31+
* class.
32+
* <p/>
33+
* <blockquote>
2634
*
27-
* Any code depending on injected fields should be done in an
28-
* {@link AfterInject} annotated method.
35+
* Example :
2936
*
30-
* The method must have zero parameters.
37+
* <pre>
38+
* &#064;EActivity(R.layout.main)
39+
* public class MyActivityTwo extends Activity {
3140
*
32-
* There may be several methods annotated with @{@link AfterInject} in the same
33-
* class.
41+
* &#064;Bean
42+
* MyBean myBean;
43+
*
44+
* &#064;AfterInject
45+
* void init() {
46+
* myBean.doSomeStuff();
47+
* }
48+
* }
49+
* </pre>
50+
*
51+
* </blockquote>
3452
*
53+
* @see AfterViews
3554
*/
3655
@Retention(RetentionPolicy.CLASS)
3756
@Target(ElementType.METHOD)

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/AfterTextChange.java‎

Lines changed: 15 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -23,56 +23,51 @@
2323
import android.text.Editable;
2424

2525
/**
26-
*
2726
* This annotation is intended to be used on methods to receive events defined
2827
* by {@link android.text.TextWatcher#afterTextChanged(Editable s)} after the
2928
* text is changed on the targeted TextView or subclass of TextView.
30-
*
29+
* <p/>
3130
* The annotation value should be one or several R.id.* fields that refers to
3231
* TextView or subclasses of TextView. If not set, the method name will be used
3332
* as the R.id.* field name.
34-
*
35-
* The method may have multiple parameter:
33+
* <p/>
34+
* The method MAY have multiple parameter:
3635
* <ul>
37-
* <li>A android.widget.TextView parameter to know which view has targeted this
38-
* event
39-
* <li>An android.text.Editable to make changes on modified text.
36+
* <li>A {@link android.widget.TextView} parameter to know which view has
37+
* targeted this event
38+
* <li>An {@link android.text.Editable} to make changes on modified text.
4039
* </ul>
40+
* <p/>
41+
* <blockquote>
4142
*
42-
* Some usage examples of &#064;BeforeTextChange annotation: <blockquote>
43+
* Example :
4344
*
4445
* <pre>
4546
* &#064;AfterTextChange(<b>R.id.helloTextView</b>)
4647
* void afterTextChangedOnHelloTextView(Editable text, TextView hello) {
4748
* // Something Here
4849
* }
49-
* </pre>
5050
*
51-
* </blockquote> <blockquote>
52-
*
53-
* <pre>
5451
* &#064;AfterTextChange
5552
* void <b>helloTextView</b>AfterTextChanged(TextView hello) {
5653
* // Something Here
5754
* }
58-
* </pre>
59-
*
60-
* </blockquote> <blockquote>
6155
*
62-
* <pre>
6356
* &#064;AfterTextChange(<b>{R.id.editText, R.id.helloTextView}</b>)
6457
* void afterTextChangedOnSomeTextViews(TextView tv, Editable text) {
6558
* // Something Here
6659
* }
67-
* </pre>
6860
*
69-
* </blockquote> <blockquote>
70-
*
71-
* <pre>
7261
* &#064;AfterTextChange(<b>R.id.helloTextView</b>)
7362
* void afterTextChangedOnHelloTextView() {
7463
* // Something Here
7564
* }
65+
* </pre>
66+
*
67+
* </blockquote>
68+
*
69+
* @see BeforeTextChange
70+
* @see TextChange
7671
*/
7772
@Retention(RetentionPolicy.CLASS)
7873
@Target(ElementType.METHOD)

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/AfterViews.java‎

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,37 @@
2525
/**
2626
* Methods annotated with @{@link AfterViews} will be called after
2727
* {@link Activity#setContentView(int)} is called by the generated activity.
28+
* <p/>
29+
* This occurs AFTER <code>setContentView(View)</code> which is called at the
30+
* end of super.onCreate(). Any view depending code should be done in an
31+
* {@link AfterViews} annotated method.
32+
* <p/>
33+
* The method MUST have zero parameters.
34+
* <p/>
35+
* There MAY be several methods annotated with @{@link AfterViews} in the same
36+
* activity.
37+
* <p/>
38+
* <blockquote>
2839
*
29-
* This occurs after <b>super.onCreate() is called</b>. Any view depending code
30-
* should be done in an {@link AfterViews} annotated method.
40+
* Example :
3141
*
32-
* The method must have zero parameters.
42+
* <pre>
43+
* &#064;EActivity(R.layout.main)
44+
* public class MyActivityTwo extends Activity {
3345
*
34-
* There may be several methods annotated with @{@link AfterViews} in the same
35-
* activity.
46+
* &#064;ViewById
47+
* TextView myTextView;
48+
*
49+
* &#064;AfterViews
50+
* void initViews() {
51+
* myTextView.setText(&quot;test);
52+
* }
53+
* }
54+
* </pre>
55+
*
56+
* </blockquote>
3657
*
58+
* @see AfterInject
3759
*/
3860
@Retention(RetentionPolicy.CLASS)
3961
@Target(ElementType.METHOD)

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/App.java‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,31 @@
2121
import java.lang.annotation.Target;
2222

2323
/**
24-
* Injects the application. Please check that your registered the application in
25-
* the AndroidManifest.xml class prior to using this annotation.
24+
* Injects an {@link EApplication} annotated class in an enhanced class.
25+
* <p/>
26+
* Please check that your registered the application in the AndroidManifest.xml
27+
* class prior to using this annotation.
28+
* <p/>
29+
* <blockquote>
30+
*
31+
* Example :
32+
*
33+
* <pre>
34+
* &#064;EApplication
35+
* public class MyApplication extends Application {
36+
* }
37+
*
38+
* &#064;EBean
39+
* public class MyBean {
40+
*
41+
* &#064;App
42+
* MyApplication myApp;
43+
* }
44+
* </pre>
45+
*
46+
* </blockquote>
47+
*
48+
* @see EApplication
2649
*/
2750
@Retention(RetentionPolicy.CLASS)
2851
@Target(ElementType.FIELD)

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/Background.java‎

Lines changed: 134 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,140 @@
1919
import java.lang.annotation.Retention;
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
22+
import java.util.concurrent.Future;
23+
import java.util.concurrent.ScheduledThreadPoolExecutor;
2224

2325
/**
24-
* Should be used on method that must be run in a background thread. This method
25-
* must belong to an activity annotated with @Layout.
26+
* Should be used on method that must be run in a background thread.
27+
* <p/>
28+
* The annotated method MUST return void and MAY contain parameters.
29+
* <p/>
30+
* The generated code is based on {@link BackgroundExecutor} methods.
2631
*
32+
*
33+
* <h2>Cancellation</h2>
34+
* Since 3.0, you're able to cancel a background task by calling
35+
* <code>BackgroundExecutor.cancelAll("id")</code> where "id" matches the
36+
* {@link #id()} value.
37+
*
38+
* <p/>
39+
* <blockquote>
40+
*
41+
* <b>Example</b> :
42+
*
43+
* <pre>
44+
* &#064;EBean
45+
* public class MyBean {
46+
* private static final String TASK_ID = &quot;task1&quot;;
47+
*
48+
* &#064;Background(id = TASK_ID)
49+
* void launchTask() {
50+
* // ...
51+
* }
52+
*
53+
* void stopTask() {
54+
* BackgroundExecutor.cancelAll(TASK_ID);
55+
* }
56+
*
57+
* }
58+
* </pre>
59+
*
60+
* </blockquote>
61+
* <p/>
62+
* <b>Note</b>: Cancellation may or may not be successful. If the task wasn't
63+
* executed yet, it will be removed from the pool. But it could fail if task has
64+
* already completed, has already been cancelled, or could not be cancelled for
65+
* some other reason. See {@link Future#cancel(boolean)} for more information.
66+
*
67+
*
68+
* <h2>Execution flow</h2>
69+
* By default, all tasks will be put in a {@link ScheduledThreadPoolExecutor}
70+
* with a core pool size of <code>2 * numberOfCpu</code>. Which means that
71+
* background methods will be executed in <b>PARALLEL</b>. You can change this
72+
* by calling <code>BackgroundExecutor.setExecutor(...)</code>.
73+
*
74+
* If you want execute ALL background methods SEQUENTIALLY, the best way is to
75+
* change the executor of {@link BackgroundExecutor} to a
76+
* {@link ScheduledThreadPoolExecutor} with a core pool size of <code>1</code>.
77+
* <p/>
78+
* If you want execute some background methods SEQUENTIALLY, you should simply
79+
* use {@link #serial()} field. All task with the same serial key will be
80+
* executed sequentially.
81+
*
82+
* <p/>
83+
* <blockquote>
84+
*
85+
* <b>Example 1</b> (all tasks executed sequentially) :
86+
*
87+
* <pre>
88+
* &#064;EBean
89+
* public class MyBean {
90+
*
91+
* static {
92+
* BackgroundExecutor.setExecutor(Executors.newScheduledThreadPool(1));
93+
* }
94+
*
95+
* private int i = 0;
96+
*
97+
* void launchTasks() {
98+
* backgroundTask();
99+
* backgroundTask();
100+
* backgroundTask();
101+
* }
102+
*
103+
* &#064;Background
104+
* void backgroundTask() {
105+
* Log.i(&quot;AA&quot;, &quot;i = &quot;, i++);
106+
* }
107+
* }
108+
* </pre>
109+
*
110+
* <b>Example 2</b> (some tasks executed sequentially) :
111+
*
112+
* <pre>
113+
* &#064;EBean
114+
* public class MyBean {
115+
*
116+
* private int i = 0;
117+
*
118+
* void launchTasks() {
119+
* backgroundTask();
120+
* backgroundTask();
121+
* backgroundTask();
122+
* }
123+
*
124+
* &#064;Background(serial = &quot;sequence1&quot;)
125+
* void backgroundTask() {
126+
* Log.i(&quot;AA&quot;, &quot;i = &quot;, i++);
127+
* }
128+
* }
129+
* </pre>
130+
*
131+
* </blockquote>
132+
*
133+
*
134+
* <h2>Delay</h2>
135+
* Sometimes you may want to delay execution of a background method. To do so,
136+
* you should use the {@link #delay()} field.
137+
* <p/>
138+
* <b>Example</b> :
139+
*
140+
* <pre>
141+
* &#064;EBean
142+
* public class MyBean {
143+
*
144+
* &#064;Background(delay = 2000)
145+
* void backgroundTask() {
146+
* // ...
147+
* }
148+
* }
149+
* </pre>
150+
*
151+
* </blockquote>
152+
*
153+
*
154+
* @see UiThread
155+
* @see BackgroundExecutor
27156
*/
28157
@Retention(RetentionPolicy.CLASS)
29158
@Target(ElementType.METHOD)
@@ -40,7 +169,9 @@
40169
**/
41170
String id() default "";
42171

43-
/** Minimum delay, in milliseconds, before the background task is executed. */
172+
/**
173+
* Minimum delay, in milliseconds, before the background task is executed.
174+
*/
44175
int delay() default 0;
45176

46177
/**

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/Bean.java‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,39 @@
2121
import java.lang.annotation.Target;
2222

2323
/**
24-
* Injects an instance of a class annotated with {@link EBean}. You can specify
25-
* the type to inject using the value attribute, otherwise
24+
* Injects an {@link EBean} annotated class in an enhanced class.
25+
* <p/>
26+
* You can specify a specific implementation to inject using the value
27+
* attribute.
28+
* <p/>
29+
* <blockquote>
30+
*
31+
* Example :
32+
*
33+
* <pre>
34+
* &#064;EActivity
35+
* public class MyActivity extends Activity {
36+
*
37+
* &#064;Bean
38+
* MyBean myBean;
39+
*
40+
* &#064;Bean(MyBean2.class)
41+
* MyBean myBean2;
42+
*
43+
* }
44+
*
45+
* &#064;EBean
46+
* public class MyBean {
47+
* }
48+
*
49+
* &#064;EBean
50+
* public class MyBean2 extends MyBean {
51+
* }
52+
* </pre>
53+
*
54+
* </blockquote>
55+
*
56+
* @see EBean
2657
*/
2758
@Retention(RetentionPolicy.CLASS)
2859
@Target(ElementType.FIELD)

0 commit comments

Comments
 (0)