1 /*
2 * Copyright 2012 smartics, Kronseder & Reiner GmbH
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package de.smartics.projectdoc.annotations;
17
18 import java.lang.annotation.Documented;
19 import java.lang.annotation.ElementType;
20 import java.lang.annotation.Retention;
21 import java.lang.annotation.RetentionPolicy;
22 import java.lang.annotation.Target;
23
24 /**
25 * Provides meta information about the document associated with the annotated
26 * element.
27 * <p>
28 * Please not that some of the annotation's information found at the type level
29 * are inherited to the elements defined in this type. These elements are
30 * explicitly documented to reflect this.
31 * </p>
32 *
33 * <pre>
34 * {@source "Usage Example"
35 * {@annotation}Document(name = "parent", shortDescription = "Parent Short Description.",
36 * notes = { "Parent Note 1", "Parent Note 2" }, space = "parent space",
37 * title = "Parent Title", sortKey = "Parent Sort Key",
38 * summary = "Parent Summary", audience = { "developer", "plugin developer" })
39 * public interface TestProperties {
40 * String inheritAll();
41 *
42 * {@annotation}Document(name = "Child Name 1",
43 * shortDescription = "Child 1 Short Description.",
44 * notes = { "Child 1 Notes" }, space = "Child 1 Space",
45 * title = "Child 1 Title", sortKey = "Child 1 Sort Key",
46 * summary = "Child 1 Summary", audience = "Child 1 Audience")
47 * String oneValue();
48 *
49 * {@annotation}Document(audience = { "Child 2 Audience 1", "Child 2 Audience 2" })
50 * String multipleValues();
51 * }
52 * }
53 * </pre>
54 *
55 * @see DocCategory
56 * @see DocParent
57 * @see DocTag
58 */
59 @Documented
60 @Target({ ElementType.TYPE, ElementType.FIELD, ElementType.METHOD })
61 @Retention(RetentionPolicy.RUNTIME)
62 public @interface Document
63 {
64 /**
65 * The name of the element as it is to be used in the documentation. This
66 * allows to specify names that are otherwise impossible due to Java naming
67 * rules.
68 * <p>
69 * At type level the content may be used as a prefix for all elements of the
70 * type.
71 * </p>
72 * <p>
73 * The name is required to be unique and is not necessarily human readable.
74 * The name may be a local name that is only unique within a given context, if
75 * this context information is be added by the parser/tool.
76 * </p>
77 * <p>
78 * This is an identification element.
79 * </p>
80 */
81 String name() default "";
82
83 /**
84 * A document may be associated with a space. While the name is required to be
85 * unique within the set of all documents, the title of a document is only
86 * unique within its space.
87 * <p>
88 * If this information is given at type level, it is inherited to the elements
89 * defined in this type (if a value is not provided explicitly on the element
90 * level).
91 * </p>
92 * <p>
93 * This is an identification element.
94 * </p>
95 */
96 String space() default "";
97
98 /**
99 * The title of the document unique within the given space.
100 * <p>
101 * This is an identification element.
102 * </p>
103 */
104 String title() default "";
105
106 /**
107 * Names the intended audience of the document.
108 * <p>
109 * If this information is given at type level, it is inherited to the elements
110 * defined in this type. Any information provided at the element level is
111 * added to the inherited values.
112 * </p>
113 * <p>
114 * This is a description element.
115 * </p>
116 */
117 String[] audience() default "";
118
119 /**
120 * A short description to be used in a tabular index.
121 * <p>
122 * At type level the content is applied to the set of properties.
123 * </p>
124 * <p>
125 * This is a description element.
126 * </p>
127 */
128 String shortDescription() default "";
129
130 /**
131 * A summary with more details than the short description.
132 * <p>
133 * At type level the content is applied to the set of properties.
134 * </p>
135 * <p>
136 * This is a description element.
137 * </p>
138 */
139 String summary() default "";
140
141 /**
142 * Some notes to be added to the documentation of the element.
143 * <p>
144 * At type level the notes are added to the notes of the individual elements.
145 * </p>
146 * <p>
147 * This is a description element.
148 * </p>
149 */
150 String[] notes() default "";
151
152 /**
153 * The optional sort key if a natural ordering on the title or name is not
154 * sufficient.
155 * <p>
156 * This is a filing element.
157 * </p>
158 *
159 * @see DocCategory
160 * @see DocTag
161 * @see DocParent
162 */
163 String sortKey() default "";
164 }