diff options
Diffstat (limited to 'src')
-rw-r--r-- | src/com/google/doclava/AndroidAuxSource.java | 40 | ||||
-rw-r--r-- | src/com/google/doclava/ClassInfo.java | 1 | ||||
-rw-r--r-- | src/com/google/doclava/Comment.java | 52 | ||||
-rw-r--r-- | src/com/google/doclava/DocInfo.java | 15 | ||||
-rw-r--r-- | src/com/google/doclava/Doclava.java | 69 | ||||
-rw-r--r-- | src/com/google/doclava/Errors.java | 1 | ||||
-rw-r--r-- | src/com/google/doclava/NavTree.java | 1 | ||||
-rw-r--r-- | src/com/google/doclava/Stubs.java | 49 |
8 files changed, 183 insertions, 45 deletions
diff --git a/src/com/google/doclava/AndroidAuxSource.java b/src/com/google/doclava/AndroidAuxSource.java index 1c97b18..ca1fbd0 100644 --- a/src/com/google/doclava/AndroidAuxSource.java +++ b/src/com/google/doclava/AndroidAuxSource.java @@ -219,6 +219,46 @@ public class AndroidAuxSource implements AuxSource { valueTags.toArray(TagInfo.getArray(valueTags.size())))); } + // Document provider columns + if ((type == TYPE_FIELD) && annotation.type().qualifiedNameMatches("android", "Column")) { + String value = null; + boolean readOnly = false; + for (AnnotationValueInfo val : annotation.elementValues()) { + switch (val.element().name()) { + case "value": + value = String.valueOf(val.value()); + break; + case "readOnly": + readOnly = Boolean.parseBoolean(String.valueOf(val.value())); + break; + } + } + + ArrayList<TagInfo> valueTags = new ArrayList<>(); + valueTags.add(new ParsedTagInfo("", "", + "{@link android.content.ContentProvider}", null, SourcePositionInfo.UNKNOWN)); + valueTags.add(new ParsedTagInfo("", "", + "{@link android.content.ContentValues}", null, SourcePositionInfo.UNKNOWN)); + valueTags.add(new ParsedTagInfo("", "", + "{@link android.database.Cursor}", null, SourcePositionInfo.UNKNOWN)); + + ClassInfo cursorClass = annotation.type().findClass("android.database.Cursor"); + for (FieldInfo field : cursorClass.fields()) { + if (field.isHiddenOrRemoved()) continue; + if (String.valueOf(field.constantValue()).equals(value)) { + valueTags.add(new ParsedTagInfo("", "", + "{@link android.database.Cursor#" + field.name() + "}", + null, SourcePositionInfo.UNKNOWN)); + } + } + if (valueTags.size() < 4) continue; + + Map<String, String> args = new HashMap<>(); + if (readOnly) args.put("readOnly", "true"); + tags.add(new AuxTagInfo("@column", "@column", SourcePositionInfo.UNKNOWN, args, + valueTags.toArray(TagInfo.getArray(valueTags.size())))); + } + // The remaining annotations below always appear on return docs, and // should not be included in the method body if (type == TYPE_METHOD) continue; diff --git a/src/com/google/doclava/ClassInfo.java b/src/com/google/doclava/ClassInfo.java index dbe7783..2a5db75 100644 --- a/src/com/google/doclava/ClassInfo.java +++ b/src/com/google/doclava/ClassInfo.java @@ -39,7 +39,6 @@ import java.util.TreeMap; import java.util.function.Predicate; public class ClassInfo extends DocInfo implements ContainerInfo, Comparable, Scoped, Resolvable { - /** * Contains a ClassInfo and a TypeInfo. * <p> diff --git a/src/com/google/doclava/Comment.java b/src/com/google/doclava/Comment.java index 63ace55..29154c2 100644 --- a/src/com/google/doclava/Comment.java +++ b/src/com/google/doclava/Comment.java @@ -30,9 +30,14 @@ public class Comment { private static final Set<String> KNOWN_TAGS = new HashSet<String>(Arrays.asList(new String[] { "@apiNote", "@author", - "@since", "@version", + //not used by metalava for Android docs (see @apiSince) + "@since", + //value is an Android API level (set automatically by metalava) + "@apiSince", "@deprecated", + //value is an Android API level (set automatically by metalava) + "@deprecatedSince", "@undeprecate", "@docRoot", "@sdkCurrent", @@ -45,8 +50,6 @@ public class Comment { "@implNote", "@implSpec", "@usesMathJax", - "@deprecatedSince", - "@apiSince", })); public Comment(String text, ContainerInfo base, SourcePositionInfo sp) { @@ -287,8 +290,6 @@ public class Comment { for (char c = text.charAt(index); index < endOfBlock && !isWhitespaceChar(c); c = text.charAt(index++)) {} - - // if (index == startOfBlock+1) { return; } @@ -330,6 +331,10 @@ public class Comment { mInlineTagsList.add(new TextTagInfo("Text", "Text", text, pos)); } else if (name.equals("@param")) { mParamTagsList.add(new ParamTagInfo("@param", "@param", text, mBase, pos)); + } else if (name.equals("@apiSince")) { + setApiSince(text); + } else if (name.equals("@deprecatedSince")) { + setDeprecatedSince(text); } else if (name.equals("@see")) { mSeeTagsList.add(new SeeTagInfo("@see", "@see", text, mBase, pos)); } else if (name.equals("@link")) { @@ -387,8 +392,16 @@ public class Comment { known = Doclava.knownTags.contains(name); } if (!known) { - Errors.error(Errors.UNKNOWN_TAG, pos == null ? null : new SourcePositionInfo(pos), - "Unknown tag: " + name); + if (name.length() >= 2 && Character.isUpperCase(name.charAt(1))) { + // This is a workaround for b/135928616 where parsing of comments fails when there is + // a Java annotation and not a tag. + Errors.error(Errors.JAVA_TAG_IN_COMMENT, + pos == null ? null : new SourcePositionInfo(pos), + "Invalid tag: " + name); + } else { + Errors.error(Errors.UNKNOWN_TAG, pos == null ? null : new SourcePositionInfo(pos), + "Unknown tag: " + name); + } } TagInfo t = new TextTagInfo(name, name, text, pos); if (isInline) { @@ -526,6 +539,29 @@ public class Comment { return mRemoved; } + public void setDeprecatedSince(String since) { + if (since != null) { + since = since.trim(); + } + mDeprecatedSince = since; + } + + public String getDeprecatedSince() { + return mDeprecatedSince; + } + + public void setApiSince(String since) { + if (since != null) { + since = since.trim(); + } + mApiSince = since; + } + + public String getApiSince() { + //return the value of @apiSince, an API level in Android + return mApiSince; + } + public boolean isDocOnly() { if (mDocOnly == null) { mDocOnly = (mText != null) && (mText.indexOf("@doconly") >= 0); @@ -601,6 +637,8 @@ public class Comment { Boolean mRemoved = null; Boolean mDocOnly = null; Boolean mDeprecated = null; + String mDeprecatedSince; + String mApiSince; String mText; ContainerInfo mBase; SourcePositionInfo mPosition; diff --git a/src/com/google/doclava/DocInfo.java b/src/com/google/doclava/DocInfo.java index 650ce0d..fae225f 100644 --- a/src/com/google/doclava/DocInfo.java +++ b/src/com/google/doclava/DocInfo.java @@ -101,6 +101,9 @@ public abstract class DocInfo { } public String getSince() { + if (Doclava.METALAVA_API_SINCE) { + mSince = comment().getApiSince(); + } return mSince; } @@ -129,11 +132,19 @@ public abstract class DocInfo { } public String getDeprecatedSince() { - return mDeprecatedSince; + if (Doclava.METALAVA_API_SINCE) { + return comment().getDeprecatedSince(); + } else { + return mDeprecatedSince; + } } public boolean isDeprecated() { - return mDeprecatedSince != null ? true : false; + if (Doclava.METALAVA_API_SINCE) { + return comment().isDeprecated(); + } else { + return mDeprecatedSince != null ? true : false; + } } public final void addFederatedReference(FederatedSite source) { diff --git a/src/com/google/doclava/Doclava.java b/src/com/google/doclava/Doclava.java index 53afe55..f24718a 100644 --- a/src/com/google/doclava/Doclava.java +++ b/src/com/google/doclava/Doclava.java @@ -82,6 +82,7 @@ public class Doclava { public static boolean NAVTREE_ONLY = false; /* Generate reference navtree.js with all inherited members */ public static boolean AT_LINKS_NAVTREE = false; + public static boolean METALAVA_API_SINCE = false; public static String outputPathBase = "/"; public static ArrayList<String> inputPathHtmlDirs = new ArrayList<String>(); public static ArrayList<String> inputPathHtmlDir2 = new ArrayList<String>(); @@ -121,6 +122,7 @@ public class Doclava { public static boolean referenceOnly = false; public static boolean staticOnly = false; public static boolean yamlV2 = false; /* whether to build the new version of the yaml file */ + public static boolean devsite = false; /* whether to build docs for devsite */ public static AuxSource auxSource = new EmptyAuxSource(); public static Linter linter = new EmptyLinter(); public static boolean android = false; @@ -193,6 +195,7 @@ public class Doclava { HashSet<String> stubPackages = null; HashSet<String> stubImportPackages = null; boolean stubSourceOnly = false; + boolean keepStubComments = false; ArrayList<String> knownTagsFiles = new ArrayList<String>(); root = r; @@ -301,6 +304,8 @@ public class Doclava { } } else if (a[0].equals("-stubsourceonly")) { stubSourceOnly = true; + } else if (a[0].equals("-keepstubcomments")) { + keepStubComments = true; } else if (a[0].equals("-sdkvalues")) { sdkValuePath = a[1]; } else if (a[0].equals("-api")) { @@ -327,6 +332,8 @@ public class Doclava { includeDefaultAssets = false; } else if (a[0].equals("-parsecomments")) { parseComments = true; + } else if (a[0].equals("-metalavaApiSince")) { + METALAVA_API_SINCE = true; } else if (a[0].equals("-since")) { sinceTagger.addVersion(a[1], a[2]); } else if (a[0].equals("-artifact")) { @@ -377,6 +384,7 @@ public class Doclava { } else if (a[0].equals("-yamlV2")) { yamlV2 = true; } else if (a[0].equals("-devsite")) { + devsite = true; // Don't copy any assets to devsite output includeAssets = false; USE_DEVSITE_LOCALE_OUTPUT_PATHS = true; @@ -386,7 +394,8 @@ public class Doclava { System.out.println(" ... Generating static html only for devsite"); } if (yamlNavFile == null) { - yamlNavFile = "_book.yaml"; + // Use _toc.yaml as default to avoid clobbering possible manual _book.yaml files + yamlNavFile = "_toc.yaml"; } } else if (a[0].equals("-android")) { auxSource = new AndroidAuxSource(); @@ -424,9 +433,8 @@ public class Doclava { } // If no custom template path is provided, and this is a devsite build, // then use the bundled templates-sdk/ files by default - if (templates.isEmpty() && USE_DEVSITE_LOCALE_OUTPUT_PATHS) { + if (templates.isEmpty() && devsite) { resourceLoaders.add(new ClassResourceLoader(Doclava.class, "/assets/templates-sdk")); - System.out.println("\n######### OK, Using templates-sdk ############\n"); } templates = ClearPage.getBundledTemplateDirs(); @@ -447,7 +455,11 @@ public class Doclava { if (NAVTREE_ONLY) { if (AT_LINKS_NAVTREE) { AtLinksNavTree.writeAtLinksNavTree(javadocDir); + } else if (yamlV2) { + // Generate DAC-formatted left-nav for devsite + NavTree.writeYamlTree2(javadocDir, yamlNavFile); } else { + // This shouldn't happen; this is the legacy DAC left nav file NavTree.writeNavTree(javadocDir, ""); } return true; @@ -518,18 +530,6 @@ public class Doclava { } else if(gcmRef){ refPrefix = "gcm-"; } - NavTree.writeNavTree(javadocDir, refPrefix); - - // Write yaml tree. - if (yamlNavFile != null){ - NavTree.writeYamlTree(javadocDir, yamlNavFile); - if (yamlV2) { - // Generate both for good measure, to make transitions easier, but change the filename - // for the new one so there's yet another explicit opt-in required by fixing the name. - yamlNavFile = "_NEW" + yamlNavFile; - NavTree.writeYamlTree2(javadocDir, yamlNavFile); - } - } // Packages Pages writePackages(refPrefix + "packages" + htmlExtension); @@ -540,6 +540,20 @@ public class Doclava { writeHierarchy(); // writeKeywords(); + // Write yaml tree. + if (yamlNavFile != null) { + if (yamlV2) { + // Generate DAC-formatted left-nav for devsite + NavTree.writeYamlTree2(javadocDir, yamlNavFile); + } else { + // Generate legacy devsite left-nav (shows sub-classes nested under parent class) + NavTree.writeYamlTree(javadocDir, yamlNavFile); + } + } else { + // This shouldn't happen; this is the legacy DAC left nav file + NavTree.writeNavTree(javadocDir, refPrefix); + } + // Lists for JavaScript writeLists(); if (keepListFile != null) { @@ -556,7 +570,7 @@ public class Doclava { if (!sTaglist.isEmpty()) { PageMetadata.WriteListByLang(sTaglist); // For devsite (ds) reference only, write samples_metadata to out dir - if ((USE_DEVSITE_LOCALE_OUTPUT_PATHS) && (!DEVSITE_STATIC_ONLY)) { + if ((devsite) && (!DEVSITE_STATIC_ONLY)) { PageMetadata.WriteSamplesListByLang(sTaglist); } } @@ -568,7 +582,7 @@ public class Doclava { || privateApiFile != null || privateDexApiFile != null || apiMappingFile != null) { Stubs.writeStubsAndApi(stubsDir, apiFile, dexApiFile, proguardFile, removedApiFile, removedDexApiFile, exactApiFile, privateApiFile, privateDexApiFile, apiMappingFile, - stubPackages, stubImportPackages, stubSourceOnly); + stubPackages, stubImportPackages, stubSourceOnly, keepStubComments); } Errors.printErrors(); @@ -853,6 +867,9 @@ public class Doclava { if (option.equals("-stubsourceonly")) { return 1; } + if (option.equals("-keepstubcomments")) { + return 1; + } if (option.equals("-sdkvalues")) { return 2; } @@ -889,6 +906,9 @@ public class Doclava { if (option.equals("-parsecomments")) { return 1; } + if (option.equals("-metalavaApiSince")) { + return 1; + } if (option.equals("-since")) { return 3; } @@ -1040,7 +1060,11 @@ public class Doclava { data.setValue("reference.gcm", "true"); } data.setValue("reference", "1"); - data.setValue("reference.apilevels", sinceTagger.hasVersions() ? "1" : "0"); + if (METALAVA_API_SINCE) { + data.setValue("reference.apilevels", (pkg.getSince() != null) ? "1" : "0"); + } else { + data.setValue("reference.apilevels", sinceTagger.hasVersions() ? "1" : "0"); + } data.setValue("reference.artifacts", artifactTagger.hasArtifacts() ? "1" : "0"); data.setValue("docs.packages." + i + ".name", s); data.setValue("docs.packages." + i + ".link", pkg.htmlPage()); @@ -1201,7 +1225,7 @@ public class Doclava { // Write the lists for JD documents (if there are HTML directories to process) // Skip this for devsite builds - if ((inputPathHtmlDirs.size() > 0) && (!USE_DEVSITE_LOCALE_OUTPUT_PATHS)) { + if ((inputPathHtmlDirs.size() > 0) && (!devsite)) { Data jddata = makeHDF(); Iterator counter = new Iterator(); for (String htmlDir : inputPathHtmlDirs) { @@ -1563,8 +1587,11 @@ public class Doclava { setPageTitle(data, "Class Index"); ClearPage.write(data, "classes.cs", packageDir + "classes" + htmlExtension); - // Index page redirects to the classes.html page, so use the same directory - writeIndex(packageDir); + if (!devsite) { + // Index page redirects to the classes.html page, so use the same directory + // This page is not needed for devsite builds, which should instead use _redirects.yaml + writeIndex(packageDir); + } } // we use the word keywords because "index" means something else in html land diff --git a/src/com/google/doclava/Errors.java b/src/com/google/doclava/Errors.java index 6b0eee0..a7a3bdf 100644 --- a/src/com/google/doclava/Errors.java +++ b/src/com/google/doclava/Errors.java @@ -314,6 +314,7 @@ public class Errors { public static final Error TODO = new Error(128, LINT); public static final Error NO_ARTIFACT_DATA = new Error(129, HIDDEN); public static final Error BROKEN_ARTIFACT_FILE = new Error(130, ERROR); + public static final Error JAVA_TAG_IN_COMMENT = new Error(131, LINT); public static boolean setErrorLevel(int code, int level) { for (Error e : sErrors) { diff --git a/src/com/google/doclava/NavTree.java b/src/com/google/doclava/NavTree.java index b4861c8..3375df5 100644 --- a/src/com/google/doclava/NavTree.java +++ b/src/com/google/doclava/NavTree.java @@ -26,6 +26,7 @@ import java.util.TreeMap; public class NavTree { + /* @deprecated This method was used for an older version of DAC, circa 2012, retired May 2018 */ public static void writeNavTree(String dir, String refPrefix) { List<Node> children = new ArrayList<Node>(); for (PackageInfo pkg : Doclava.choosePackages()) { diff --git a/src/com/google/doclava/Stubs.java b/src/com/google/doclava/Stubs.java index 0ef3749..930d52c 100644 --- a/src/com/google/doclava/Stubs.java +++ b/src/com/google/doclava/Stubs.java @@ -49,7 +49,8 @@ public class Stubs { public static void writeStubsAndApi(String stubsDir, String apiFile, String dexApiFile, String keepListFile, String removedApiFile, String removedDexApiFile, String exactApiFile, String privateApiFile, String privateDexApiFile, String apiMappingFile, - HashSet<String> stubPackages, HashSet<String> stubImportPackages, boolean stubSourceOnly) { + HashSet<String> stubPackages, HashSet<String> stubImportPackages, boolean stubSourceOnly, + boolean keepStubComments) { // figure out which classes we need final HashSet<ClassInfo> notStrippable = new HashSet<ClassInfo>(); Collection<ClassInfo> all = Converter.allClasses(); @@ -259,7 +260,7 @@ public class Stubs { if (shouldWriteStub(cl.containingPackage().name(), stubPackages, stubPackageWildcards)) { // write out the stubs if (stubsDir != null) { - writeClassFile(stubsDir, notStrippable, cl); + writeClassFile(stubsDir, notStrippable, cl, keepStubComments); } // build class list for api file or keep list file if (apiWriter != null || dexApiWriter != null || keepListWriter != null) { @@ -588,7 +589,7 @@ public class Stubs { return dir + cl.name() + ".java"; } - static void writeClassFile(String stubsDir, HashSet<ClassInfo> notStrippable, ClassInfo cl) { + static void writeClassFile(String stubsDir, HashSet<ClassInfo> notStrippable, ClassInfo cl, boolean keepStubComments) { // inner classes are written by their containing class if (cl.containingClass() != null) { return; @@ -608,7 +609,7 @@ public class Stubs { PrintStream stream = null; try { stream = new PrintStream(new BufferedOutputStream(new FileOutputStream(file))); - writeClassFile(stream, notStrippable, cl); + writeClassFile(stream, notStrippable, cl, keepStubComments); } catch (FileNotFoundException e) { System.err.println("error writing file: " + filename); } finally { @@ -618,7 +619,7 @@ public class Stubs { } } - static void writeClassFile(PrintStream stream, HashSet<ClassInfo> notStrippable, ClassInfo cl) { + static void writeClassFile(PrintStream stream, HashSet<ClassInfo> notStrippable, ClassInfo cl, boolean keepStubComments) { PackageInfo pkg = cl.containingPackage(); if (cl.containingClass() == null) { stream.print(parseLicenseHeader(cl.position())); @@ -626,7 +627,7 @@ public class Stubs { if (pkg != null) { stream.println("package " + pkg.name() + ";"); } - writeClass(stream, notStrippable, cl); + writeClass(stream, notStrippable, cl, keepStubComments); } private static String parseLicenseHeader(/* @Nonnull */ SourcePositionInfo positionInfo) { @@ -677,7 +678,11 @@ public class Stubs { return builder.toString(); } - static void writeClass(PrintStream stream, HashSet<ClassInfo> notStrippable, ClassInfo cl) { + static void writeClass(PrintStream stream, HashSet<ClassInfo> notStrippable, ClassInfo cl, boolean keepStubComments) { + if (keepStubComments) { + writeComment(stream, cl); + } + writeAnnotations(stream, cl.annotations(), cl.isDeprecated()); stream.print(cl.scope() + " "); @@ -752,14 +757,14 @@ public class Stubs { for (ClassInfo inner : cl.getRealInnerClasses()) { if (notStrippable.contains(inner) && !inner.isDocOnly()) { - writeClass(stream, notStrippable, inner); + writeClass(stream, notStrippable, inner, keepStubComments); } } for (MethodInfo method : cl.constructors()) { if (!method.isDocOnly()) { - writeMethod(stream, method, true); + writeMethod(stream, method, true, keepStubComments); } } @@ -806,7 +811,7 @@ public class Stubs { } } if (!method.isDocOnly()) { - writeMethod(stream, method, false); + writeMethod(stream, method, false, keepStubComments); } } // Write all methods that are hidden or removed, but override abstract methods or interface methods. @@ -823,7 +828,7 @@ public class Stubs { (overriddenMethod.isAbstract() || overriddenMethod.containingClass().isInterface())) { method.setReason("1:" + classContainingMethod.qualifiedName()); cl.addMethod(method); - writeMethod(stream, method, false); + writeMethod(stream, method, false, keepStubComments); } } @@ -835,7 +840,7 @@ public class Stubs { for (FieldInfo field : cl.selfFields()) { if (!field.isDocOnly()) { - writeField(stream, field); + writeField(stream, field, keepStubComments); } } @@ -853,7 +858,10 @@ public class Stubs { stream.println("}"); } - static void writeMethod(PrintStream stream, MethodInfo method, boolean isConstructor) { + static void writeMethod(PrintStream stream, MethodInfo method, boolean isConstructor, boolean keepStubComments) { + if (keepStubComments) { + writeComment(stream, method); + } String comma; writeAnnotations(stream, method.annotations(), method.isDeprecated()); @@ -924,7 +932,10 @@ public class Stubs { } } - static void writeField(PrintStream stream, FieldInfo field) { + static void writeField(PrintStream stream, FieldInfo field, boolean keepStubComments) { + if (keepStubComments) { + writeComment(stream, field); + } writeAnnotations(stream, field.annotations(), field.isDeprecated()); stream.print(field.scope() + " "); @@ -1090,6 +1101,16 @@ public class Stubs { stream.println(";"); } + static void writeComment(PrintStream stream, DocInfo doc) { + if (!doc.isHiddenOrRemoved() && !doc.comment().isDocOnly() && !"".equals(doc.getRawCommentText())) { + String newLineSeparator = System.getProperty("line.separator"); + stream.println("/**"); + stream.print(" * "); + stream.println(doc.getRawCommentText().replace(newLineSeparator, newLineSeparator + " *")); + stream.println(" */"); + } + } + public static void writeXml(PrintStream xmlWriter, Collection<PackageInfo> pkgs, boolean strip) { if (strip) { Stubs.writeXml(xmlWriter, pkgs); |