Skip to content

Commit 74fd5f1

Browse files
DaySDayS
committed
Improve javadoc for root annotations
1 parent 5c20925 commit 74fd5f1

10 files changed

Lines changed: 445 additions & 68 deletions

File tree

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

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

2323
/**
24-
* Should be used on Activity classes to enable usage of AndroidAnnotations
25-
*
24+
* Should be used on {@link android.app.Activity} classes to enable usage of
25+
* AndroidAnnotations.
26+
* <p/>
27+
* Your code related to injected beans should go in an {@link AfterInject}
28+
* annotated method.
29+
* <p/>
2630
* Any view related code should happen in an {@link AfterViews} annotated
2731
* method.
28-
*
32+
* <p/>
33+
* If the class is abstract, the enhanced activity will not be generated.
34+
* Otherwise, it will be generated as a final class. You can use
35+
* AndroidAnnotations to create Abstract classes that handle common code.
36+
* <p/>
2937
* The annotation value should be one of R.layout.* fields. If not set, no
3038
* content view will be set, and you should call the setContentView() method
3139
* yourself, in <b>onCreate()</b>
40+
* <p/>
41+
* The generated class will also contain an IntentBuilder to start activity with
42+
* a fluent API. Android's extra can also be enhanced by using {@link Extra}
43+
* annotation on every native or serializable/parcelable field.
44+
* <p/>
45+
* <blockquote>
3246
*
33-
* If the activity is abstract, the generated activity will not be final.
34-
* Otherwise, it will be final. You can use AndroidAnnotations to create
35-
* Abstract classes that handle common code, but we want you to make a clear
36-
* decision on that subject.
47+
* Example :
3748
*
38-
* The main reason is that the generated code should not be considered a public
39-
* API, and may change between releases. So if you extend some generated
40-
* activity, you may have to adapt your code when you upgrade
41-
* AndroidAnnotations.
49+
* <pre>
50+
* &#064;EActivity(R.layout.main)
51+
* public class MyActivity extends Activity {
52+
*
53+
* public void launchActivity() {
54+
* // Note the use of generated class instead of original one
55+
* MyActivityTwo_.intent(this)
56+
* .myExtra("test")
57+
* .startActivity();
58+
* }
59+
*
60+
* }
61+
*
62+
* <pre>
63+
* &#064;EActivity(R.layout.main)
64+
* public class MyActivityTwo extends Activity {
65+
*
66+
* &#064;Bean
67+
* MyBean myBean;
68+
*
69+
* &#064;ViewById
70+
* TextView myTextView;
71+
*
72+
* &#064;Extra
73+
* String myExtra;
74+
*
75+
* &#064;AfterInject
76+
* void init() {
77+
* myBean.doSomeStuff();
78+
* }
79+
*
80+
* &#064;AfterViews
81+
* void initViews() {
82+
* myTextView.setText(myExtra);
83+
* }
84+
* }
85+
* </pre>
86+
*
87+
* </blockquote>
4288
*
89+
* @see AfterInject
90+
* @see AfterViews
91+
* @see Extra
4392
*/
4493
@Retention(RetentionPolicy.CLASS)
4594
@Target(ElementType.TYPE)

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

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,51 @@
2121
import java.lang.annotation.Target;
2222

2323
/**
24-
* Should be used on android.app.Application classes to enable usage of
25-
* AndroidAnnotations
24+
* Should be used on {@link android.app.Application} classes to enable usage of
25+
* AndroidAnnotations.
26+
* <p/>
27+
* Your code related to injected beans should go in an {@link AfterInject}
28+
* annotated method.
29+
* <p/>
30+
* If the class is abstract, the enhanced application will not be generated.
31+
* Otherwise, it will be generated as a final class. You can use
32+
* AndroidAnnotations to create Abstract classes that handle common code.
33+
* <p/>
34+
* Most annotations are supported in {@link EApplication} classes, except the
35+
* ones related to views and extras.
36+
* <p/>
37+
* The enhanced application can also be injected in any enhanced class by using
38+
* {@link App} annotation.
39+
* <p/>
40+
* <blockquote>
2641
*
27-
* Most annotations are supported in {@link EApplication} classes
42+
* Example :
2843
*
44+
* <pre>
45+
* &#064;EApplication
46+
* public class MyApplication extends Application {
47+
*
48+
* &#064;Bean
49+
* MyBean myBean;
50+
*
51+
* &#064;AfterInject
52+
* void init() {
53+
* myBean.doSomeStuff();
54+
* }
55+
* }
56+
*
57+
* &#064;EBean
58+
* public class MyBean {
59+
*
60+
* &#064;App
61+
* MyApplication myApp;
62+
* }
63+
* </pre>
64+
*
65+
* </blockquote>
66+
*
67+
* @see AfterInject
68+
* @see App
2969
*/
3070
@Retention(RetentionPolicy.CLASS)
3171
@Target(ElementType.TYPE)

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

Lines changed: 56 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,19 +21,66 @@
2121
import java.lang.annotation.Target;
2222

2323
/**
24-
* Should be used on custom classes to enable usage of AndroidAnnotations
24+
* Should be used on custom classes to enable usage of AndroidAnnotations.
25+
* <p/>
26+
* Your code related to injected beans should go in an {@link AfterInject}
27+
* annotated method.
28+
* <p/>
29+
* If the class is abstract, the enhanced bean will not be generated. Otherwise,
30+
* it will be generated as a final class. You can use AndroidAnnotations to
31+
* create Abstract classes that handle common code.
32+
* <p/>
33+
* Most annotations are supported in {@link EBean} classes, except the ones
34+
* related to extras. Views related annotations will only work if the bean was
35+
* injected in an activity with a layout containing the views you're dealing
36+
* with. If your bean needs a {@link android.app.Context} you can inject on by
37+
* using an {@link RootContext} annotated field.
38+
* <p/>
39+
* Beans have two possible scopes : default or singleton. Default scope should
40+
* be prefered but in some case it may be useful to use a singleton scope
41+
* (mainly if you want to keep some runtime state in your bean).
42+
* <p/>
43+
* The enhanced bean can also be injected in any enhanced class by using
44+
* {@link Bean} annotation.
45+
* <p/>
46+
* <blockquote>
2547
*
26-
* Any view related code should happen in an {@link AfterViews} annotated
27-
* method.<br>
28-
* <br>
48+
* Example :
2949
*
30-
* Most annotations are supported in {@link EBean} classes
50+
* <pre>
51+
* &#064;EBean
52+
* public class MyBean {
3153
*
54+
* &#064;RootContext
55+
* Context context;
56+
* &#064;Bean
57+
* MySingletonBean mySingletonBean;
58+
*
59+
* &#064;AfterInject
60+
* void init() {
61+
* mySingletonBean.doSomeStuff(context);
62+
* }
63+
* }
64+
*
65+
* &#064;EBean(scope = Scope.Singleton)
66+
* public class MySingletonBean {
67+
*
68+
* public void doSomeStuff(Context context) {
69+
* // ...
70+
* }
71+
* }
72+
* </pre>
73+
*
74+
* </blockquote>
75+
*
76+
* @see AfterInject
77+
* @see RootContext
78+
* @see Bean
3279
*/
3380
@Retention(RetentionPolicy.CLASS)
3481
@Target(ElementType.TYPE)
3582
public @interface EBean {
36-
83+
3784
public enum Scope {
3885

3986
/**
@@ -42,12 +89,12 @@ public enum Scope {
4289
Default, //
4390

4491
/**
45-
* A new instance of the bean is created the first time it is needed, it is
46-
* then retained and the same instance is always returned.
92+
* A new instance of the bean is created the first time it is needed, it
93+
* is then retained and the same instance is always returned.
4794
*/
4895
Singleton, //
4996
}
5097

5198
Scope scope() default Scope.Default;
52-
99+
53100
}

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

Lines changed: 67 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,75 @@
2121
import java.lang.annotation.Target;
2222

2323
/**
24-
* Should be used on Fragment classes to enable usage of AndroidAnnotations
24+
* Should be used on {@link android.app.Fragment} or
25+
* {@link android.support.v4.app.Fragment} classes to enable usage of
26+
* AndroidAnnotations.
27+
* <p/>
28+
* Your code related to injected beans should go in an {@link AfterInject}
29+
* annotated method.
30+
* <p/>
31+
* Any view related code should happen in an {@link AfterViews} annotated
32+
* method.
33+
* <p/>
34+
* If the class is abstract, the enhanced activity will not be generated.
35+
* Otherwise, it will be generated as a final class. You can use
36+
* AndroidAnnotations to create Abstract classes that handle common code.
37+
* <p/>
38+
* The annotation value should be one of R.layout.* fields. If not set, no
39+
* content view will be set, and you should call the setContentView() method
40+
* yourself, in <b>onCreate()</b>
41+
* <p/>
42+
* The generated class will also contain a FragmentBuilder to build fragment
43+
* with a fluent API. Arguments can be passed by using {@link FragmentArg}
44+
* annotation on every native or serializable/parcelable field.
45+
* <p/>
46+
* The enhanced fragment can also be retrieved (not injected in layout) in any
47+
* enhanced class by using {@link FragmentById} or {@link FragmentByTag}
48+
* annotations.
49+
* <p/>
50+
* <blockquote>
2551
*
26-
* The annotation value should be one of R.layout.* fields, or none if you want
27-
* to handle the view creation by yourself.
52+
* Example :
2853
*
54+
* <pre>
55+
* &#064;EFragment(R.layout.fragment)
56+
* public class MyFragment extends Fragment {
57+
*
58+
* &#064;Bean
59+
* MyBean myBean;
60+
*
61+
* &#064;ViewById
62+
* TextView myTextView;
63+
*
64+
* &#064;FragmentArg
65+
* String myExtra;
66+
*
67+
* &#064;AfterInject
68+
* void init() {
69+
* myBean.doSomeStuff();
70+
* }
71+
*
72+
* &#064;AfterViews
73+
* void initViews() {
74+
* myTextView.setText(myExtra);
75+
* }
76+
* }
77+
*
78+
* &#064;EActivity(R.layout.main)
79+
* public class MyActivity extends Activity {
80+
*
81+
* &#064;FragmentById
82+
* MyFragment myFragment;
83+
* }
84+
* </pre>
85+
*
86+
* </blockquote>
87+
*
88+
* @see AfterInject
89+
* @see AfterViews
90+
* @see FragmentById
91+
* @see FragmentByTag
92+
* @see FragmentArg
2993
*/
3094
@Retention(RetentionPolicy.CLASS)
3195
@Target(ElementType.TYPE)

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

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,60 @@
2121
import java.lang.annotation.Target;
2222

2323
/**
24-
* Use this annotation to enhance an Android IntentService
24+
* Should be used on {@link android.app.IntentService} classes to enable usage
25+
* of AndroidAnnotations.
26+
* <p/>
27+
* Your code related to injected beans should go in an {@link AfterInject}
28+
* annotated method.
29+
* <p/>
30+
* If the class is abstract, the enhanced intentservice will not be generated.
31+
* Otherwise, it will be generated as a final class. You can use
32+
* AndroidAnnotations to create Abstract classes that handle common code.
33+
* <p/>
34+
* The generated class will also contain an IntentBuilder to start activity with
35+
* a fluent API. Android's extra can also be enhanced by using {@link Extra}
36+
* annotation on every native or serializable/parcelable field.
37+
* <p/>
38+
* The IntentService class should contain a {@link ServiceAction} annotated
39+
* method in order to respond to an action.
40+
* <p/>
41+
* <blockquote>
42+
*
43+
* Example :
44+
*
45+
* <pre>
46+
* &#064;EActivity(R.layout.main)
47+
* public class MyActivity extends Activity {
48+
*
49+
* public void launchAction() {
50+
* // Note the use of generated class instead of original one
51+
* MyIntentService_.intent(this)
52+
* .myAction("test", 10L)
53+
* .start();
54+
* }
55+
*
56+
* }
57+
*
58+
* <pre>
59+
* &#064;EIntentService
60+
* public class MyIntentService extends IntentService {
61+
*
62+
* &#064;ServiceAction
63+
* void mySimpleAction() {
64+
* // ...
65+
* }
66+
*
67+
* &#064;ServiceAction
68+
* void myAction(String valueString, long valueLong) {
69+
* // ...
70+
* }
71+
* }
72+
* </pre>
73+
*
74+
* </blockquote>
75+
*
76+
* @see AfterInject
77+
* @see ServiceAction
2578
*/
2679
@Retention(RetentionPolicy.CLASS)
2780
@Target(ElementType.TYPE)

0 commit comments

Comments
 (0)