| /* |
| * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package sampleapi.generator; |
| |
| import java.io.File; |
| import java.io.BufferedInputStream; |
| import java.io.IOException; |
| import java.util.Set; |
| import javax.lang.model.element.Modifier; |
| |
| import com.sun.tools.javac.tree.JCTree; |
| import com.sun.tools.javac.tree.JCTree.*; |
| import com.sun.tools.javac.util.List; |
| import java.util.HashMap; |
| import java.util.Map; |
| |
| class DocCommentGenerator { |
| |
| public enum Text { |
| BROWNFOX(BROWNFOX_TEXT), |
| NOWISTHETIME(NOWISTHETIME_TEXT), |
| THISPANGRAM(THISPANGRAM_TEXT), |
| LOREMIPSUM(LOREMIPSUM_TEXT), |
| LIEUROPANLINGUES(LIEUROPANLINGUES_TEXT), |
| CODE(CODE_TEXT); |
| |
| String commentText; |
| |
| Text(String text) { |
| commentText = text; |
| } |
| |
| @Override |
| public String toString() { |
| return commentText; |
| } |
| } |
| |
| public enum Tag { |
| AUTHOR("@author", "Cody J. Writer"), |
| PARAM("@param", ""), |
| RETURN("@return", Text.NOWISTHETIME.toString()), |
| SINCE("@since", "1.0"), |
| THROWS("@throws", "If problem detected"), |
| EXCEPTION("@exception", "If problem detected"), |
| SERIAL("@serial", ""), |
| SERIALDATA("@serialData", "The types and order of data could be here."), |
| SERIALFIELD("@serialField", "\n Serial field in special array"), |
| FX_PROPSETTER("@propertySetter", "Set the property"), |
| FX_PROPGETTER("@propertyGetter", "Get the property"), |
| FX_PROPDESC("@propertyDescription", ""), |
| FX_DEFVALUE("@defaultValue", ""), |
| FX_TREATASPRIVATE("@treatAsPrivate", ""); |
| |
| String tagName; |
| String tagValue; |
| |
| Tag(String tagName, String tagValue) { |
| this.tagName = tagName; |
| this.tagValue = tagValue; |
| } |
| |
| public String toString() { |
| return value("", ""); |
| } |
| |
| public String value(String value) { |
| return value(value, ""); |
| } |
| |
| public String value(String value, String extra) { |
| return tagName |
| + ((value.length() != 0) ? " " + value : "") |
| + ((tagValue.length() != 0) ? " " + tagValue : "") |
| + ((extra.length() != 0) ? " " + extra : ""); |
| } |
| } |
| |
| public enum InlineTag { |
| LITERAL("@literal", "Use < and > brackets instead of < and > escapes."), |
| CODE("@code", "(i) -> new Abc<Object>((i > 0) ? (i << 1) : 0)"), |
| LINK("@link", ""), |
| VALUE("@value", ""), |
| INDEX("@index", "", true); |
| |
| String tagName; |
| String tagValue; |
| boolean counted; |
| Map<String, Integer> counters; |
| |
| InlineTag(String tagName, String tagValue) { |
| this(tagName, tagValue, false); |
| } |
| |
| InlineTag(String tagName, String tagValue, boolean counted) { |
| this.tagName = tagName; |
| this.tagValue = tagValue; |
| this.counted = counted; |
| if (counted) { |
| counters = new HashMap<>(); |
| } |
| } |
| |
| public String toString() { |
| return value(""); |
| } |
| |
| public String value(String value) { |
| String name = ((tagValue.length() != 0) ? " " + tagValue : "") |
| + ((value.length() != 0) ? " " + value : ""); |
| if (counted && !counters.containsKey(name)) { |
| counters.put(name, 0); |
| } |
| return "{" + tagName |
| + name |
| + (counted ? "_" + counters.put(name, counters.get(name) + 1) : "") |
| + "}"; |
| } |
| } |
| |
| public static class LinkTag { |
| |
| static String[] links = new String[] { |
| "Boolean", |
| "Boolean#TRUE", |
| "Boolean#Boolean(boolean)", |
| "Boolean#Boolean(String s)", |
| "Boolean#compare(boolean, boolean)", |
| "Boolean#compareTo(Boolean b)", |
| "java.util.Vector", |
| "java.util.Vector#elementCount", |
| "java.util.Vector#Vector(int)", |
| "java.util.Vector#Vector(int initialCapacity, int capacityIncrement)", |
| "java.util.Vector#indexOf(Object)", |
| "java.util.Vector#indexOf(Object o, int index)", |
| "java.lang.annotation" }; |
| |
| static int index = 0; |
| |
| public static String nextSee() { |
| String next = "@see " + links[index]; |
| index = (index + 1) % links.length; |
| return next; |
| } |
| |
| public static String nextLink() { |
| String next = "Also check " |
| + (((index % 2) == 0) ? "{@link " : "{@linkplain ") |
| + links[index] |
| + "} for details.\n"; |
| index = (index + 1) % links.length; |
| return next; |
| } |
| } |
| |
| public static class VersionTag { |
| |
| static String[] versions = new String[] { |
| "1.5, 09/01/04", |
| "1.6, 12/11/06", |
| "1.7, 07/28/11", |
| "1.8, 04/19/14", |
| "9, 06/03/16" }; |
| |
| static int index = 0; |
| |
| public static String nextVersion() { |
| String next = "@version " + versions[index]; |
| index = (index + 1) % versions.length; |
| return next; |
| } |
| } |
| |
| // |
| // getters (build comments for entities) |
| // |
| |
| public String getPackageComment() { |
| return InlineTag.INDEX.value("PackageCommentLabel") + " " |
| + Text.LOREMIPSUM |
| + "\n<p>" + Text.LIEUROPANLINGUES |
| + "\n" + Text.CODE |
| + "\n" + LinkTag.nextLink() |
| + "\n" + LinkTag.nextSee() |
| + "\n" + Tag.SINCE + "\n"; |
| } |
| |
| String[] serialVals = new String[] { "include", "exclude" }; |
| // static index to roll over "include/exclude" |
| static int serialValIdx = 0; |
| |
| public String getBaseComment(JCClassDecl baseDecl, boolean toplevel) { |
| String buildComment = InlineTag.INDEX.value("BaseCommentLabel") + " "; |
| |
| buildComment += Text.LIEUROPANLINGUES + "\n"; |
| |
| buildComment += "<p>It is possible to see inlined code:\n" |
| + InlineTag.CODE |
| + " is the example.\n\n"; |
| |
| buildComment += "<p>Literal use example.\n" |
| + InlineTag.LITERAL + "\n\n"; |
| |
| buildComment += "<p>" + Text.THISPANGRAM + "\n"; // make comment longer |
| |
| buildComment += "<p>" + LinkTag.nextLink() + "\n"; |
| |
| if (toplevel) |
| buildComment += "\n" + VersionTag.nextVersion() + "\n"; |
| |
| // @param for type params |
| List<JCTypeParameter> params = baseDecl.getTypeParameters(); |
| int paramIndex = 0; |
| for (JCTypeParameter paramDecl : params) { |
| buildComment += Tag.PARAM.value( |
| "<" + paramDecl.getName().toString() + ">", |
| "the type of value set #" + paramIndex++) |
| + "\n"; |
| } |
| |
| buildComment += "\n" + LinkTag.nextSee(); |
| |
| buildComment += "\n"; |
| |
| if (toplevel) |
| buildComment += Tag.AUTHOR + "\n"; |
| |
| buildComment += Tag.SINCE + "\n"; |
| |
| // for serial; currently no need to dig too deep |
| if (isSerializable(baseDecl) || isErrorOrException(baseDecl)) { |
| buildComment += "\n" + Tag.SERIAL.value(serialVals[serialValIdx]); |
| serialValIdx = (serialValIdx + 1) % 2; |
| } |
| |
| return buildComment; |
| } |
| |
| public String getConstComment() { |
| String buildComment = InlineTag.INDEX.value("ConstCommentLabel") + " "; |
| |
| buildComment += Text.NOWISTHETIME + " " + Text.BROWNFOX + "\n"; |
| buildComment += LinkTag.nextLink() + "\n"; |
| buildComment += LinkTag.nextSee() + "\n"; |
| buildComment += Tag.SINCE + "\n"; |
| |
| return buildComment; |
| } |
| |
| public String getFieldComment(JCClassDecl baseDecl, |
| JCVariableDecl varDecl, |
| boolean isFxStyle) { |
| String buildComment = InlineTag.INDEX.value("FieldCommentLabel") + " "; |
| |
| buildComment += Text.BROWNFOX + "<p>" + Text.NOWISTHETIME + "\n"; |
| Set<Modifier> mods = varDecl.getModifiers().getFlags(); |
| String varName = varDecl.getName().toString(); |
| |
| if (mods.contains(Modifier.STATIC) && mods.contains(Modifier.FINAL)) { |
| JCExpression init = varDecl.getInitializer(); |
| if (init != null |
| && !"null".equals(init.toString()) |
| && !"serialPersistentFields".equals(varName)) |
| buildComment += "<p>The value of this constant is " |
| + InlineTag.VALUE |
| + ".\n"; |
| } |
| |
| buildComment += "<p>" + LinkTag.nextLink() + "\n"; |
| |
| if (isSerializable(baseDecl)) { |
| if (isErrorOrException(baseDecl)) { |
| buildComment += Tag.SERIAL + "\n"; |
| } else if ("serialPersistentFields".equals(varName)) { |
| JCNewArray sfList = (JCNewArray)varDecl.getInitializer(); |
| for (JCExpression sf : sfList.getInitializers()) { |
| List<JCExpression> args = ((JCNewClass)sf).getArguments(); |
| String sfName = ((JCLiteral)args.get(0)).getValue().toString(); |
| String sfClass = ((JCIdent)args.get(1)).getName().toString(); |
| String sfType = sfClass.substring(0, sfClass.indexOf(".class")); |
| |
| buildComment += Tag.SERIALFIELD.value(sfName + " " + sfType) |
| + "\n"; |
| } |
| } else { |
| buildComment += Tag.SERIAL.value("Very important value.") + "\n"; |
| } |
| } |
| |
| if (isFxStyle) { |
| // set default value |
| String varType = varDecl.getType().toString(); |
| buildComment += Tag.FX_DEFVALUE.value(defValue(varType)) + "\n"; |
| } |
| |
| buildComment += LinkTag.nextSee() + "\n"; |
| |
| return buildComment; |
| } |
| |
| public String getMethodComment(JCClassDecl baseDecl, |
| JCMethodDecl methodDecl, |
| boolean isFxStyle) { |
| String buildComment = InlineTag.INDEX.value("MethodCommentLabel") + " "; |
| |
| buildComment += Text.BROWNFOX + "\n<p>" + Text.THISPANGRAM + "\n"; |
| |
| buildComment += "<p>" + LinkTag.nextLink() + "\n"; |
| |
| buildComment += "<p>Literal use example.\n" |
| + InlineTag.LITERAL + "\n\n"; |
| |
| // @param for type params |
| List<JCTypeParameter> tparams = methodDecl.getTypeParameters(); |
| int tparamIndex = 0; |
| for (JCTypeParameter paramDecl : tparams) { |
| String paramDeclString = paramDecl.getName().toString(); |
| // simplify it (could contain 'extend'/'super' clauses |
| int spacePos = paramDeclString.indexOf(' '); |
| if (spacePos != -1) |
| paramDeclString = paramDeclString.substring(0, spacePos); |
| buildComment += Tag.PARAM.value( |
| "<" + paramDeclString + ">", |
| "the type of value set #" + tparamIndex++) |
| + "\n"; |
| } |
| |
| // @param |
| List<JCVariableDecl> params = methodDecl.getParameters(); |
| int paramIndex = 0; |
| for (JCVariableDecl paramDecl : params) { |
| buildComment += Tag.PARAM.value( |
| paramDecl.getName().toString(), |
| "an income parameter #" + paramIndex++) |
| + "\n"; |
| } |
| |
| // @return |
| JCTree retType = methodDecl.getReturnType(); // null for constructors |
| if (retType != null && !"void".equals(retType.toString())) |
| buildComment += Tag.RETURN + "\n"; |
| |
| // @throws/@exception |
| Tag t = isDerived(baseDecl) ? Tag.EXCEPTION : Tag.THROWS; |
| List<JCExpression> throwTypes = methodDecl.getThrows(); |
| for (JCExpression throwsExp : throwTypes) { |
| buildComment += t.value(throwsExp.toString()) + "\n"; |
| } |
| |
| if (isSerializable(baseDecl)) { |
| switch (methodDecl.getName().toString()) { |
| case "writeObject": |
| case "readObject": |
| case "writeExternal": |
| case "readExternal": |
| case "writeReplace": |
| case "readResolve": |
| buildComment += Tag.SERIALDATA + "\n"; |
| break; |
| default: |
| } |
| } |
| |
| if (isFxStyle) { |
| // @propertySetter/Getter + Description |
| if ("void".equals(retType.toString())) { |
| buildComment += Tag.FX_PROPSETTER + "\n"; |
| } else { |
| buildComment += Tag.FX_PROPGETTER + "\n"; |
| buildComment += Tag.FX_DEFVALUE.value(defValue(retType.toString())) |
| + "\n"; |
| } |
| buildComment += Tag.FX_PROPDESC.value(Text.BROWNFOX.toString()) + "\n"; |
| |
| // @treatAsPrivate |
| if (methodDecl.getModifiers().getFlags().contains(Modifier.PUBLIC)) |
| buildComment += Tag.FX_TREATASPRIVATE + "\n"; |
| } |
| |
| // @see |
| buildComment += LinkTag.nextSee() + "\n"; |
| |
| // @since |
| buildComment += Tag.SINCE + "\n"; |
| |
| return buildComment; |
| } |
| |
| // |
| // util methods |
| // |
| |
| private boolean isErrorOrException(JCClassDecl baseDecl) { |
| JCExpression ext = baseDecl.getExtendsClause(); |
| if (ext != null) { |
| String extClassName = ext.toString(); |
| if (extClassName.contains("Error") || extClassName.contains("Exception")) |
| return true; |
| } |
| return false; |
| } |
| |
| private boolean isSerializable(JCClassDecl baseDecl) { |
| List<JCExpression> impls = baseDecl.getImplementsClause(); |
| for (JCExpression impl : impls) { |
| if (impl.toString().contains("Serializable")) |
| return true; |
| } |
| return false; |
| } |
| |
| private boolean isDerived(JCClassDecl baseDecl) { |
| return (baseDecl.getExtendsClause() == null) ? false : true; |
| } |
| |
| private String defValue(String type) { |
| switch (type) { |
| case "boolean": |
| return "true"; |
| case "byte": case "char": case "int": case "long": |
| case "Integer": case "Long": |
| return "1"; |
| case "float": case "double": case "Float": case "Double": |
| return "1.0"; |
| case "String": |
| return "string"; |
| default: |
| return "null"; |
| } |
| } |
| |
| private static final String BROWNFOX_TEXT = |
| "The quick brown fox jumps over the lazy dog.\n"; |
| private static final String NOWISTHETIME_TEXT = |
| "Now is the time for all good men to come to the aid of the party.\n"; |
| private static final String THISPANGRAM_TEXT = |
| "This pangram contains four a's, one b, two c's, one d, thirty e's,\n" + |
| "six f's, five g's, seven h's, eleven i's, one j, one k, two l's,\n" + |
| "two m's, eighteen n's, fifteen o's, two p's, one q, five r's,\n" + |
| "twenty-seven s's, eighteen t's, two u's, seven v's, eight w's,\n" + |
| "two x's, three y's, & one z."; |
| private static final String LOREMIPSUM_TEXT = |
| "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do\n" + |
| "eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut\n" + |
| "enim ad minim veniam, quis nostrud exercitation ullamco laboris\n" + |
| "nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor\n" + |
| "in reprehenderit in voluptate velit esse cillum dolore eu fugiat\n" + |
| "nulla pariatur. Excepteur sint occaecat cupidatat non proident,\n" + |
| "sunt in culpa qui officia deserunt mollit anim id est laborum.\n"; |
| private static final String LIEUROPANLINGUES_TEXT = |
| "Li Europan lingues es membres del sam familie. Lor separat existentie\n" + |
| "es un myth. Por scientie, musica, sport etc, litot Europa usa li sam\n" + |
| "vocabular. Li lingues differe solmen in li grammatica, li pronunciation\n" + |
| "e li plu commun vocabules. Omnicos directe al desirabilite de un nov\n" + |
| "lingua franca: On refusa continuar payar custosi traductores.\n" + |
| "\n" + |
| "<p>At solmen va esser necessi far uniform grammatica, pronunciation\n" + |
| "e plu commun paroles. Ma quande lingues coalesce, li grammatica del\n" + |
| "resultant lingue es plu simplic e regulari quam ti del coalescent\n" + |
| "lingues. Li nov lingua franca va esser plu simplic e regulari quam\n" + |
| "li existent Europan lingues. It va esser tam simplic quam Occidental\n" + |
| "in fact, it va esser Occidental. A un Angleso it va semblar un simplificat\n" + |
| "Angles, quam un skeptic Cambridge amico dit me que Occidental es.\n"; |
| private static final String CODE_TEXT = |
| "<pre>\n" + |
| "public void checkLanguage(Language lang) throws Exception {\n" + |
| " if (lang.getName().equals(\"Java\")) {\n" + |
| " System.out.println(\"Warning! Hot!\");\n" + |
| " else {\n" + |
| " throw new LooserException();\n" + |
| " }\n" + |
| "}\n" + |
| "</pre>\n"; |
| } |
