1 /*
2 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 */
23
24 package sampleapi.generator;
25
26 import java.io.File;
27 import java.io.BufferedInputStream;
28 import java.io.IOException;
29 import java.util.Set;
30 import javax.lang.model.element.Modifier;
31
32 import com.sun.tools.javac.tree.JCTree;
33 import com.sun.tools.javac.tree.JCTree.*;
34 import com.sun.tools.javac.util.List;
35
36 class DocCommentGenerator {
37
38 public enum Text {
39 BROWNFOX(BROWNFOX_TEXT),
40 NOWISTHETIME(NOWISTHETIME_TEXT),
41 THISPANGRAM(THISPANGRAM_TEXT),
42 LOREMIPSUM(LOREMIPSUM_TEXT),
43 LIEUROPANLINGUES(LIEUROPANLINGUES_TEXT),
44 CODE(CODE_TEXT);
45
46 String commentText;
47
48 Text(String text) {
49 commentText = text;
50 }
51
52 @Override
53 public String toString() {
54 return commentText;
55 }
56 }
57
58 public enum Tag {
59 AUTHOR("@author", "Cody J. Writer"),
60 PARAM("@param", ""),
61 RETURN("@return", Text.NOWISTHETIME.toString()),
62 SINCE("@since", "1.0"),
63 THROWS("@throws", "If problem detected"),
64 EXCEPTION("@exception", "If problem detected"),
65 SERIAL("@serial", ""),
66 SERIALDATA("@serialData", "The types and order of data could be here."),
67 SERIALFIELD("@serialField", "\n Serial field in special array"),
68 FX_PROPSETTER("@propertySetter", "Set the property"),
69 FX_PROPGETTER("@propertyGetter", "Get the property"),
70 FX_PROPDESC("@propertyDescription", ""),
71 FX_DEFVALUE("@defaultValue", ""),
72 FX_TREATASPRIVATE("@treatAsPrivate", "");
73
74 String tagName;
75 String tagValue;
76
77 Tag(String tagName, String tagValue) {
78 this.tagName = tagName;
79 this.tagValue = tagValue;
80 }
81
82 public String toString() {
83 return value("", "");
84 }
85
86 public String value(String value) {
87 return value(value, "");
88 }
89
90 public String value(String value, String extra) {
91 return tagName
92 + ((value.length() != 0) ? " " + value : "")
93 + ((tagValue.length() != 0) ? " " + tagValue : "")
94 + ((extra.length() != 0) ? " " + extra : "");
95 }
96 }
97
98 public enum InlineTag {
99 LITERAL("@literal", "Use < and > brackets instead of < and > escapes."),
100 CODE("@code", "(i) -> new Abc<Object>((i > 0) ? (i << 1) : 0)"),
101 LINK("@link", ""),
102 VALUE("@value", "");
103
104 String tagName;
105 String tagValue;
106
107 InlineTag(String tagName, String tagValue) {
108 this.tagName = tagName;
109 this.tagValue = tagValue;
110 }
111
112 public String toString() {
113 return value("");
114 }
115
116 public String value(String value) {
117 return "{" + tagName
118 + ((tagValue.length() != 0) ? " " + tagValue : "")
119 + ((value.length() != 0) ? " " + value : "")
120 + "}";
121 }
122 }
123
124 public static class LinkTag {
125
126 static String[] links = new String[] {
127 "Boolean",
128 "Boolean#TRUE",
129 "Boolean#Boolean(boolean)",
130 "Boolean#Boolean(String s)",
131 "Boolean#compare(boolean, boolean)",
132 "Boolean#compareTo(Boolean b)",
133 "java.util.Vector",
134 "java.util.Vector#elementCount",
135 "java.util.Vector#Vector(int)",
136 "java.util.Vector#Vector(int initialCapacity, int capacityIncrement)",
137 "java.util.Vector#indexOf(Object)",
138 "java.util.Vector#indexOf(Object o, int index)",
139 "java.lang.annotation" };
140
141 static int index = 0;
142
143 public static String nextSee() {
144 String next = "@see " + links[index];
145 index = (index + 1) % links.length;
146 return next;
147 }
148
149 public static String nextLink() {
150 String next = "Also check "
151 + (((index % 2) == 0) ? "{@link " : "{@linkplain ")
152 + links[index]
153 + "} for details.\n";
154 index = (index + 1) % links.length;
155 return next;
156 }
157 }
158
159 public static class VersionTag {
160
161 static String[] versions = new String[] {
162 "1.5, 09/01/04",
163 "1.6, 12/11/06",
164 "1.7, 07/28/11",
165 "1.8, 04/19/14",
166 "9, 06/03/16" };
167
168 static int index = 0;
169
170 public static String nextVersion() {
171 String next = "@version " + versions[index];
172 index = (index + 1) % versions.length;
173 return next;
174 }
175 }
176
177 //
178 // getters (build comments for entities)
179 //
180
181 public String getPackageComment() {
182 return Text.LOREMIPSUM
183 + "\n <p>" + Text.LIEUROPANLINGUES
184 + "\n" + Text.CODE
185 + "\n" + LinkTag.nextLink()
186 + "\n" + LinkTag.nextSee()
187 + "\n" + Tag.SINCE;
188 }
189
190 String[] serialVals = new String[] { "include", "exclude" };
191 // static index to roll over "include/exclude"
192 static int serialValIdx = 0;
193
194 public String getBaseComment(JCClassDecl baseDecl, boolean toplevel) {
195 String buildComment = Text.LIEUROPANLINGUES + "\n";
196
197 buildComment += "<p>It is possible to see inlined code:\n"
198 + InlineTag.CODE
199 + " is the example.\n\n";
200
201 buildComment += "<p>Literal use example.\n"
202 + InlineTag.LITERAL + "\n\n";
203
204 buildComment += "<p>" + Text.THISPANGRAM + "\n"; // make comment longer
205
206 buildComment += "<p>" + LinkTag.nextLink() + "\n";
207
208 if (toplevel)
209 buildComment += "\n" + VersionTag.nextVersion() + "\n";
210
211 // @param for type params
212 List<JCTypeParameter> params = baseDecl.getTypeParameters();
213 int paramIndex = 0;
214 for (JCTypeParameter paramDecl : params) {
215 buildComment += Tag.PARAM.value(
216 "<" + paramDecl.getName().toString() + ">",
217 "the type of value set #" + paramIndex++)
218 + "\n";
219 }
220
221 buildComment += "\n" + LinkTag.nextSee();
222
223 buildComment += "\n";
224
225 if (toplevel)
226 buildComment += Tag.AUTHOR + "\n";
227
228 buildComment += Tag.SINCE + "\n";
229
230 // for serial; currently no need to dig too deep
231 if (isSerializable(baseDecl) || isErrorOrException(baseDecl)) {
232 buildComment += "\n" + Tag.SERIAL.value(serialVals[serialValIdx]);
233 serialValIdx = (serialValIdx + 1) % 2;
234 }
235
236 return buildComment;
237 }
238
239 public String getConstComment() {
240 String buildComment = Text.NOWISTHETIME + " " + Text.BROWNFOX + "\n";
241
242 buildComment += LinkTag.nextLink() + "\n";
243 buildComment += LinkTag.nextSee() + "\n";
244 buildComment += Tag.SINCE + "\n";
245
246 return buildComment;
247 }
248
249 public String getFieldComment(JCClassDecl baseDecl,
250 JCVariableDecl varDecl,
251 boolean isFxStyle) {
252 String buildComment = Text.BROWNFOX + "<p>" + Text.NOWISTHETIME + "\n";
253
254 Set<Modifier> mods = varDecl.getModifiers().getFlags();
255 String varName = varDecl.getName().toString();
256
257 if (mods.contains(Modifier.STATIC) && mods.contains(Modifier.FINAL)) {
258 JCExpression init = varDecl.getInitializer();
259 if (init != null
260 && !"null".equals(init.toString())
261 && !"serialPersistentFields".equals(varName))
262 buildComment += "<p>The value of this constant is "
263 + InlineTag.VALUE
264 + ".\n";
265 }
266
267 buildComment += "<p>" + LinkTag.nextLink() + "\n";
268
269 if (isSerializable(baseDecl)) {
270 if (isErrorOrException(baseDecl)) {
271 buildComment += Tag.SERIAL + "\n";
272 } else if ("serialPersistentFields".equals(varName)) {
273 JCNewArray sfList = (JCNewArray)varDecl.getInitializer();
274 for (JCExpression sf : sfList.getInitializers()) {
275 List<JCExpression> args = ((JCNewClass)sf).getArguments();
276 String sfName = ((JCLiteral)args.get(0)).getValue().toString();
277 String sfClass = ((JCIdent)args.get(1)).getName().toString();
278 String sfType = sfClass.substring(0, sfClass.indexOf(".class"));
279
280 buildComment += Tag.SERIALFIELD.value(sfName + " " + sfType)
281 + "\n";
282 }
283 } else {
284 buildComment += Tag.SERIAL.value("Very important value.") + "\n";
285 }
286 }
287
288 if (isFxStyle) {
289 // set default value
290 String varType = varDecl.getType().toString();
291 buildComment += Tag.FX_DEFVALUE.value(defValue(varType)) + "\n";
292 }
293
294 buildComment += LinkTag.nextSee() + "\n";
295
296 return buildComment;
297 }
298
299 public String getMethodComment(JCClassDecl baseDecl,
300 JCMethodDecl methodDecl,
301 boolean isFxStyle) {
302 String buildComment = Text.BROWNFOX + "\n<p>" + Text.THISPANGRAM + "\n";
303
304 buildComment += "<p>" + LinkTag.nextLink() + "\n";
305
306 buildComment += "<p>Literal use example.\n"
307 + InlineTag.LITERAL + "\n\n";
308
309 // @param for type params
310 List<JCTypeParameter> tparams = methodDecl.getTypeParameters();
311 int tparamIndex = 0;
312 for (JCTypeParameter paramDecl : tparams) {
313 String paramDeclString = paramDecl.getName().toString();
314 // simplify it (could contain 'extend'/'super' clauses
315 int spacePos = paramDeclString.indexOf(' ');
316 if (spacePos != -1)
317 paramDeclString = paramDeclString.substring(0, spacePos);
318 buildComment += Tag.PARAM.value(
319 "<" + paramDeclString + ">",
320 "the type of value set #" + tparamIndex++)
321 + "\n";
322 }
323
324 // @param
325 List<JCVariableDecl> params = methodDecl.getParameters();
326 int paramIndex = 0;
327 for (JCVariableDecl paramDecl : params) {
328 buildComment += Tag.PARAM.value(
329 paramDecl.getName().toString(),
330 "an income parameter #" + paramIndex++)
331 + "\n";
332 }
333
334 // @return
335 JCTree retType = methodDecl.getReturnType(); // null for constructors
336 if (retType != null && !"void".equals(retType.toString()))
337 buildComment += Tag.RETURN + "\n";
338
339 // @throws/@exception
340 Tag t = isDerived(baseDecl) ? Tag.EXCEPTION : Tag.THROWS;
341 List<JCExpression> throwTypes = methodDecl.getThrows();
342 for (JCExpression throwsExp : throwTypes) {
343 buildComment += t.value(throwsExp.toString()) + "\n";
344 }
345
346 if (isSerializable(baseDecl)) {
347 switch (methodDecl.getName().toString()) {
348 case "writeObject":
349 case "readObject":
350 case "writeExternal":
351 case "readExternal":
352 case "writeReplace":
353 case "readResolve":
354 buildComment += Tag.SERIALDATA + "\n";
355 break;
356 default:
357 }
358 }
359
360 if (isFxStyle) {
361 // @propertySetter/Getter + Description
362 if ("void".equals(retType.toString())) {
363 buildComment += Tag.FX_PROPSETTER + "\n";
364 } else {
365 buildComment += Tag.FX_PROPGETTER + "\n";
366 buildComment += Tag.FX_DEFVALUE.value(defValue(retType.toString()))
367 + "\n";
368 }
369 buildComment += Tag.FX_PROPDESC.value(Text.BROWNFOX.toString()) + "\n";
370
371 // @treatAsPrivate
372 if (methodDecl.getModifiers().getFlags().contains(Modifier.PUBLIC))
373 buildComment += Tag.FX_TREATASPRIVATE + "\n";
374 }
375
376 // @see
377 buildComment += LinkTag.nextSee() + "\n";
378
379 // @since
380 buildComment += Tag.SINCE + "\n";
381
382 return buildComment;
383 }
384
385 //
386 // util methods
387 //
388
389 private boolean isErrorOrException(JCClassDecl baseDecl) {
390 JCExpression ext = baseDecl.getExtendsClause();
391 if (ext != null) {
392 String extClassName = ext.toString();
393 if (extClassName.contains("Error") || extClassName.contains("Exception"))
394 return true;
395 }
396 return false;
397 }
398
399 private boolean isSerializable(JCClassDecl baseDecl) {
400 List<JCExpression> impls = baseDecl.getImplementsClause();
401 for (JCExpression impl : impls) {
402 if (impl.toString().contains("Serializable"))
403 return true;
404 }
405 return false;
406 }
407
408 private boolean isDerived(JCClassDecl baseDecl) {
409 return (baseDecl.getExtendsClause() == null) ? false : true;
410 }
411
412 private String defValue(String type) {
413 switch (type) {
414 case "boolean":
415 return "true";
416 case "byte": case "char": case "int": case "long":
417 case "Integer": case "Long":
418 return "1";
419 case "float": case "double": case "Float": case "Double":
420 return "1.0";
421 case "String":
422 return "string";
423 default:
424 return "null";
425 }
426 }
427
428 private static final String BROWNFOX_TEXT =
429 "The quick brown fox jumps over the lazy dog.\n";
430 private static final String NOWISTHETIME_TEXT =
431 "Now is the time for all good men to come to the aid of the party.\n";
432 private static final String THISPANGRAM_TEXT =
433 "This pangram contains four a's, one b, two c's, one d, thirty e's,\n" +
434 "six f's, five g's, seven h's, eleven i's, one j, one k, two l's,\n" +
435 "two m's, eighteen n's, fifteen o's, two p's, one q, five r's,\n" +
436 "twenty-seven s's, eighteen t's, two u's, seven v's, eight w's,\n" +
437 "two x's, three y's, & one z.";
438 private static final String LOREMIPSUM_TEXT =
439 "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do\n" +
440 "eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut\n" +
441 "enim ad minim veniam, quis nostrud exercitation ullamco laboris\n" +
442 "nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor\n" +
443 "in reprehenderit in voluptate velit esse cillum dolore eu fugiat\n" +
444 "nulla pariatur. Excepteur sint occaecat cupidatat non proident,\n" +
445 "sunt in culpa qui officia deserunt mollit anim id est laborum.\n";
446 private static final String LIEUROPANLINGUES_TEXT =
447 "Li Europan lingues es membres del sam familie. Lor separat existentie\n" +
448 "es un myth. Por scientie, musica, sport etc, litot Europa usa li sam\n" +
449 "vocabular. Li lingues differe solmen in li grammatica, li pronunciation\n" +
450 "e li plu commun vocabules. Omnicos directe al desirabilite de un nov\n" +
451 "lingua franca: On refusa continuar payar custosi traductores.\n" +
452 "\n" +
453 "<p>At solmen va esser necessi far uniform grammatica, pronunciation\n" +
454 "e plu commun paroles. Ma quande lingues coalesce, li grammatica del\n" +
455 "resultant lingue es plu simplic e regulari quam ti del coalescent\n" +
456 "lingues. Li nov lingua franca va esser plu simplic e regulari quam\n" +
457 "li existent Europan lingues. It va esser tam simplic quam Occidental\n" +
458 "in fact, it va esser Occidental. A un Angleso it va semblar un simplificat\n" +
459 "Angles, quam un skeptic Cambridge amico dit me que Occidental es.\n";
460 private static final String CODE_TEXT =
461 "<pre>\n" +
462 "public void checkLanguage(Language lang) throws Exception {\n" +
463 " if (lang.getName().equals(\"Java\")) {\n" +
464 " System.out.println(\"Warning! Hot!\");\n" +
465 " else {\n" +
466 " throw new LooserException();\n" +
467 " }\n" +
468 "}\n" +
469 "</pre>\n";
470 }