001: /*
002: * The contents of this file are subject to the terms
003: * of the Common Development and Distribution License
004: * (the "License"). You may not use this file except
005: * in compliance with the License.
006: *
007: * You can obtain a copy of the license at
008: * https://jwsdp.dev.java.net/CDDLv1.0.html
009: * See the License for the specific language governing
010: * permissions and limitations under the License.
011: *
012: * When distributing Covered Code, include this CDDL
013: * HEADER in each file and include the License file at
014: * https://jwsdp.dev.java.net/CDDLv1.0.html If applicable,
015: * add the following below this CDDL HEADER, with the
016: * fields enclosed by brackets "[]" replaced with your
017: * own identifying information: Portions Copyright [yyyy]
018: * [name of copyright owner]
019: */
020: package com.sun.codemodel;
021:
022: import java.util.HashMap;
023: import java.util.Map;
024:
025: /**
026: * JavaDoc comment.
027: *
028: * <p>
029: * A javadoc comment consists of multiple parts. There's the main part (that comes the first in
030: * in the comment section), then the parameter parts (@param), the return part (@return),
031: * and the throws parts (@throws).
032: *
033: * TODO: it would be nice if we have JComment class and we can derive this class from there.
034: */
035: public class JDocComment extends JCommentPart implements JGenerable {
036:
037: /** list of @param tags */
038: private final Map<String, JCommentPart> atParams = new HashMap<String, JCommentPart>();
039:
040: /** list of xdoclets */
041: private final Map<String, Map<String, String>> atXdoclets = new HashMap<String, Map<String, String>>();
042:
043: /** list of @throws tags */
044: private final Map<JClass, JCommentPart> atThrows = new HashMap<JClass, JCommentPart>();
045:
046: /**
047: * The @return tag part.
048: */
049: private JCommentPart atReturn = null;
050:
051: /** The @deprecated tag */
052: private JCommentPart atDeprecated = null;
053:
054: private final JCodeModel owner;
055:
056: public JDocComment(JCodeModel owner) {
057: this .owner = owner;
058: }
059:
060: public JDocComment append(Object o) {
061: add(o);
062: return this ;
063: }
064:
065: /**
066: * Append a text to a @param tag to the javadoc
067: */
068: public JCommentPart addParam(String param) {
069: JCommentPart p = atParams.get(param);
070: if (p == null)
071: atParams.put(param, p = new JCommentPart());
072: return p;
073: }
074:
075: /**
076: * Append a text to an @param tag.
077: */
078: public JCommentPart addParam(JVar param) {
079: return addParam(param.name());
080: }
081:
082: /**
083: * add an @throws tag to the javadoc
084: */
085: public JCommentPart addThrows(Class exception) {
086: return addThrows(owner.ref(exception));
087: }
088:
089: /**
090: * add an @throws tag to the javadoc
091: */
092: public JCommentPart addThrows(JClass exception) {
093: JCommentPart p = atThrows.get(exception);
094: if (p == null)
095: atThrows.put(exception, p = new JCommentPart());
096: return p;
097: }
098:
099: /**
100: * Appends a text to @return tag.
101: */
102: public JCommentPart addReturn() {
103: if (atReturn == null)
104: atReturn = new JCommentPart();
105: return atReturn;
106: }
107:
108: /**
109: * add an @deprecated tag to the javadoc, with the associated message.
110: */
111: public JCommentPart addDeprecated() {
112: if (atDeprecated == null)
113: atDeprecated = new JCommentPart();
114: return atDeprecated;
115: }
116:
117: /**
118: * add an xdoclet.
119: */
120: public Map<String, String> addXdoclet(String name) {
121: Map<String, String> p = atXdoclets.get(name);
122: if (p == null)
123: atXdoclets.put(name, p = new HashMap<String, String>());
124: return p;
125: }
126:
127: /**
128: * add an xdoclet.
129: */
130: public Map<String, String> addXdoclet(String name,
131: Map<String, String> attributes) {
132: Map<String, String> p = atXdoclets.get(name);
133: if (p == null)
134: atXdoclets.put(name, p = new HashMap<String, String>());
135: p.putAll(attributes);
136: return p;
137: }
138:
139: /**
140: * add an xdoclet.
141: */
142: public Map<String, String> addXdoclet(String name,
143: String attribute, String value) {
144: Map<String, String> p = atXdoclets.get(name);
145: if (p == null)
146: atXdoclets.put(name, p = new HashMap<String, String>());
147: p.put(attribute, value);
148: return p;
149: }
150:
151: public void generate(JFormatter f) {
152: // I realized that we can't use StringTokenizer because
153: // this will recognize multiple \n as one token.
154:
155: f.p("/**").nl();
156:
157: format(f, " * ");
158:
159: f.p(" * ").nl();
160: for (Map.Entry<String, JCommentPart> e : atParams.entrySet()) {
161: f.p(" * @param ").p(e.getKey()).nl();
162: e.getValue().format(f, INDENT);
163: }
164: if (atReturn != null) {
165: f.p(" * @return").nl();
166: atReturn.format(f, INDENT);
167: }
168: for (Map.Entry<JClass, JCommentPart> e : atThrows.entrySet()) {
169: f.p(" * @throws ").t(e.getKey()).nl();
170: e.getValue().format(f, INDENT);
171: }
172: if (atDeprecated != null) {
173: f.p(" * @deprecated").nl();
174: atDeprecated.format(f, INDENT);
175: }
176: for (Map.Entry<String, Map<String, String>> e : atXdoclets
177: .entrySet()) {
178: f.p(" * @").p(e.getKey());
179: if (e.getValue() != null) {
180: for (Map.Entry<String, String> a : e.getValue()
181: .entrySet()) {
182: f.p(" ").p(a.getKey()).p("= \"").p(a.getValue()).p(
183: "\"");
184: }
185: }
186: f.nl();
187: }
188: f.p(" */").nl();
189: }
190:
191: private static final String INDENT = " * ";
192: }
|