am b0d318f7: (-s ours) am 8bfc32ba: DO NOT MERGE - Infer document and sample metadata when generating docs.
* commit 'b0d318f71a6357550f00d1c429fa3ede03005df2':
DO NOT MERGE - Infer document and sample metadata when generating docs.
diff --git a/Android.mk b/Android.mk
index 7e7686d..6e4ff82 100644
--- a/Android.mk
+++ b/Android.mk
@@ -24,9 +24,7 @@
jsilver \
guavalib \
antlr-runtime
-
-LOCAL_STATIC_JAVA_LIBRARIES += tagsouplib
-
+
LOCAL_CLASSPATH := \
$(HOST_JDK_TOOLS_JAR)
diff --git a/build.gradle b/build.gradle
index 79d856e..7a2c99e 100644
--- a/build.gradle
+++ b/build.gradle
@@ -26,5 +26,4 @@
compile files(findToolsJar())
compile project(path: ':antlr', configuration: 'antlrRuntime')
compile project(':jsilver')
- compile project(':tagsoup')
}
\ No newline at end of file
diff --git a/src/com/google/doclava/ClassInfo.java b/src/com/google/doclava/ClassInfo.java
index a750b11..3cda7ec 100644
--- a/src/com/google/doclava/ClassInfo.java
+++ b/src/com/google/doclava/ClassInfo.java
@@ -117,10 +117,18 @@
mRealInterfaces = new ArrayList<ClassInfo>(interfaces);
mRealInterfaceTypes = interfaceTypes;
mInnerClasses = innerClasses;
+ // mAllConstructors will not contain *all* constructors. Only the constructors that pass
+ // checkLevel. @see {@link Converter#convertMethods(ConstructorDoc[])}
mAllConstructors = constructors;
+ // mAllSelfMethods will not contain *all* self methods. Only the methods that pass
+ // checkLevel. @see {@link Converter#convertMethods(MethodDoc[])}
mAllSelfMethods = methods;
mAnnotationElements = annotationElements;
+ // mAllSelfFields will not contain *all* self fields. Only the fields that pass
+ // checkLevel. @see {@link Converter#convetFields(FieldDoc[])}
mAllSelfFields = fields;
+ // mEnumConstants will not contain *all* enum constants. Only the enums that pass
+ // checkLevel. @see {@link Converter#convetFields(FieldDoc[])}
mEnumConstants = enumConstants;
mContainingPackage = containingPackage;
mContainingClass = containingClass;
@@ -162,16 +170,17 @@
return mTypeParameters;
}
+ /**
+ * @return true if this class needs to be shown in api txt, based on the
+ * hidden/removed status of the class and the show level setting in doclava.
+ */
public boolean checkLevel() {
- int val = mCheckLevel;
- if (val >= 0) {
- return val != 0;
- } else {
- boolean v =
- Doclava.checkLevel(mIsPublic, mIsProtected, mIsPackagePrivate, mIsPrivate, isHidden());
- mCheckLevel = v ? 1 : 0;
- return v;
+ if (mCheckLevel == null) {
+ mCheckLevel = Doclava.checkLevel(mIsPublic, mIsProtected, mIsPackagePrivate, mIsPrivate,
+ isHiddenOrRemoved());
}
+
+ return mCheckLevel;
}
public int compareTo(Object that) {
@@ -350,7 +359,7 @@
mConstructors = new ArrayList<MethodInfo>();
for (MethodInfo m : mAllConstructors) {
- if (!m.isHidden()) {
+ if (!m.isHiddenOrRemoved()) {
mConstructors.add(m);
}
}
@@ -462,13 +471,13 @@
}
for (FieldInfo field : selfFields()) {
- if (!field.isHidden()) {
+ if (!field.isHiddenOrRemoved()) {
all.put(field.name(), field);
}
}
for (FieldInfo enumConst : mEnumConstants) {
- if (!enumConst.isHidden()) {
+ if (!enumConst.isHiddenOrRemoved()) {
all.put(enumConst.name(), enumConst);
}
}
@@ -500,7 +509,7 @@
}
for (FieldInfo f : mAllSelfFields) {
- if (!f.isHidden()) {
+ if (!f.isHiddenOrRemoved()) {
fields.put(f.name(), f);
}
}
@@ -539,7 +548,7 @@
if (mAllSelfMethods != null) {
for (MethodInfo m : mAllSelfMethods) {
if (m.checkLevel()) {
- methods.put(m.name() + m.signature(), m);
+ methods.put(m.name() + m.signature(), m);
}
}
}
@@ -555,6 +564,150 @@
return mAllSelfMethods;
}
+ /**
+ * @param removedMethods the removed methods regardless of access levels.
+ */
+ public void setRemovedMethods(List<MethodInfo> removedMethods) {
+ Collections.sort(removedMethods, MethodInfo.comparator);
+ mRemovedMethods = Collections.unmodifiableList(removedMethods);
+ }
+
+ /**
+ * @param allMethods all methods regardless of access levels. Selects the
+ * removed, public/protected ones and store them. If a class is removed, all its members
+ * are removed, even if the member may not have a @removed tag.
+ */
+ public void setRemovedSelfMethods(List<MethodInfo> allMethods) {
+ List<MethodInfo> removedSelfMethods = new ArrayList<MethodInfo>();
+ for (MethodInfo method : allMethods) {
+ if ((this.isRemoved() || method.isRemoved()) && (method.isPublic() || method.isProtected()) &&
+ (this.isPublic() || this.isProtected()) &&
+ (method.findOverriddenMethod(method.name(), method.signature()) == null)) {
+ removedSelfMethods.add(method);
+ }
+ }
+
+ Collections.sort(removedSelfMethods, MethodInfo.comparator);
+ mRemovedSelfMethods = Collections.unmodifiableList(removedSelfMethods);
+ }
+
+ /**
+ * @param allCtors all constructors regardless of access levels.
+ * But only the public/protected removed constructors will be stored by the method.
+ * Removed constructors should never be deleted from source code because
+ * they were once public API.
+ */
+ public void setRemovedConstructors(List<MethodInfo> allCtors) {
+ List<MethodInfo> ctors = new ArrayList<MethodInfo>();
+ for (MethodInfo ctor : allCtors) {
+ if ((this.isRemoved() || ctor.isRemoved()) && (ctor.isPublic() || ctor.isProtected()) &&
+ (this.isPublic() || this.isProtected())) {
+ ctors.add(ctor);
+ }
+ }
+
+ Collections.sort(ctors, MethodInfo.comparator);
+ mRemovedConstructors = Collections.unmodifiableList(ctors);
+ }
+
+ /**
+ * @param allFields all fields regardless of access levels. Selects the
+ * removed, public/protected ones and store them. If a class is removed, all its members
+ * are removed, even if the member may not have a @removed tag.
+ */
+ public void setRemovedSelfFields(List<FieldInfo> allFields) {
+ List<FieldInfo> fields = new ArrayList<FieldInfo>();
+ for (FieldInfo field : allFields) {
+ if ((this.isRemoved() || field.isRemoved()) && (field.isPublic() || field.isProtected()) &&
+ (this.isPublic() || this.isProtected())) {
+ fields.add(field);
+ }
+ }
+
+ Collections.sort(fields, FieldInfo.comparator);
+ mRemovedSelfFields = Collections.unmodifiableList(fields);
+ }
+
+ /**
+ * @param allEnumConstants all enum constants regardless of access levels. Selects the
+ * removed, public/protected ones and store them. If a class is removed, all its members
+ * are removed, even if the member may not have a @removed tag.
+ */
+ public void setRemovedEnumConstants(List<FieldInfo> allEnumConstants) {
+ List<FieldInfo> enums = new ArrayList<FieldInfo>();
+ for (FieldInfo field : allEnumConstants) {
+ if ((this.isRemoved() || field.isRemoved()) && (field.isPublic() || field.isProtected()) &&
+ (this.isPublic() || this.isProtected())) {
+ enums.add(field);
+ }
+ }
+
+ Collections.sort(enums, FieldInfo.comparator);
+ mRemovedEnumConstants = Collections.unmodifiableList(enums);
+ }
+
+ /**
+ * @return all methods that are marked as removed, regardless of access levels.
+ * The returned list is sorted and unmodifiable.
+ */
+ public List<MethodInfo> getRemovedMethods() {
+ return mRemovedMethods;
+ }
+
+ /**
+ * @return all public/protected methods that are removed. @removed methods should never be
+ * deleted from source code because they were once public API. Methods that override
+ * a parent method will not be included, because deleting them does not break the API.
+ */
+ public List<MethodInfo> getRemovedSelfMethods() {
+ return mRemovedSelfMethods;
+ }
+
+ /**
+ * @return all public constructors that are removed.
+ * removed constructors should never be deleted from source code because they
+ * were once public API.
+ * The returned list is sorted and unmodifiable.
+ */
+ public List<MethodInfo> getRemovedConstructors() {
+ return mRemovedConstructors;
+ }
+
+ /**
+ * @return all public/protected fields that are removed.
+ * removed members should never be deleted from source code because they were once public API.
+ * The returned list is sorted and unmodifiable.
+ */
+ public List<FieldInfo> getRemovedSelfFields() {
+ return mRemovedSelfFields;
+ }
+
+ /**
+ * @return all public/protected enumConstants that are removed.
+ * removed members should never be deleted from source code
+ * because they were once public API.
+ * The returned list is sorted and unmodifiable.
+ */
+ public List<FieldInfo> getRemovedSelfEnumConstants() {
+ return mRemovedEnumConstants;
+ }
+
+ /**
+ * @return true if this class contains any self members that are removed
+ */
+ public boolean hasRemovedSelfMembers() {
+ List<FieldInfo> removedSelfFields = getRemovedSelfFields();
+ List<FieldInfo> removedSelfEnumConstants = getRemovedSelfEnumConstants();
+ List<MethodInfo> removedSelfMethods = getRemovedSelfMethods();
+ List<MethodInfo> removedConstructors = getRemovedConstructors();
+ if (removedSelfFields.size() + removedSelfEnumConstants.size()
+ + removedSelfMethods.size() + removedConstructors.size() == 0) {
+ return false;
+ } else {
+ return true;
+ }
+ }
+
public void addMethod(MethodInfo method) {
mApiCheckMethods.put(method.getHashableName(), method);
@@ -1195,29 +1348,26 @@
@Override
public boolean isHidden() {
- int val = mHidden;
- if (val >= 0) {
- return val != 0;
- } else {
- boolean v = isHiddenImpl();
- mHidden = v ? 1 : 0;
- return v;
+ if (mHidden == null) {
+ mHidden = isHiddenImpl();
}
+
+ return mHidden;
}
+ /**
+ * @return true if the containing package has @hide comment, or an ancestor
+ * class of this class is hidden, or this class has @hide comment.
+ */
public boolean isHiddenImpl() {
ClassInfo cl = this;
while (cl != null) {
- PackageInfo pkg = cl.containingPackage();
- if (pkg != null && pkg.isHidden()) {
- return true;
+ if (cl.hasShowAnnotation()) {
+ return false;
}
- if (cl.annotations() != null) {
- for (AnnotationInstanceInfo info : cl.annotations()) {
- if (Doclava.showAnnotations.contains(info.type().qualifiedName())) {
- return false;
- }
- }
+ PackageInfo pkg = cl.containingPackage();
+ if (pkg != null && pkg.hasHideComment()) {
+ return true;
}
if (cl.comment().isHidden()) {
return true;
@@ -1227,6 +1377,53 @@
return false;
}
+ @Override
+ public boolean isRemoved() {
+ if (mRemoved == null) {
+ mRemoved = isRemovedImpl();
+ }
+
+ return mRemoved;
+ }
+
+ /**
+ * @return true if the containing package has @removed comment, or an ancestor
+ * class of this class is removed, or this class has @removed comment.
+ */
+ public boolean isRemovedImpl() {
+ ClassInfo cl = this;
+ while (cl != null) {
+ if (cl.hasShowAnnotation()) {
+ return false;
+ }
+ PackageInfo pkg = cl.containingPackage();
+ if (pkg != null && pkg.hasRemovedComment()) {
+ return true;
+ }
+ if (cl.comment().isRemoved()) {
+ return true;
+ }
+ cl = cl.containingClass();
+ }
+ return false;
+ }
+
+ @Override
+ public boolean isHiddenOrRemoved() {
+ return isHidden() || isRemoved();
+ }
+
+ public boolean hasShowAnnotation() {
+ if (annotations() != null) {
+ for (AnnotationInstanceInfo info : annotations()) {
+ if (Doclava.showAnnotations.contains(info.type().qualifiedName())) {
+ return true;
+ }
+ }
+ }
+ return false;
+ }
+
private MethodInfo matchMethod(ArrayList<MethodInfo> methods, String name, String[] params,
String[] dimensions, boolean varargs) {
for (MethodInfo method : methods) {
@@ -1474,7 +1671,11 @@
private ArrayList<ClassInfo> mInterfaces;
private ArrayList<TypeInfo> mRealInterfaceTypes;
private ArrayList<ClassInfo> mInnerClasses;
+ // mAllConstructors will not contain *all* constructors. Only the constructors that pass
+ // checkLevel. @see {@link Converter#convertMethods(ConstructorDoc[])}
private ArrayList<MethodInfo> mAllConstructors = new ArrayList<MethodInfo>();
+ // mAllSelfMethods will not contain *all* self methods. Only the methods that pass
+ // checkLevel. @see {@link Converter#convertMethods(MethodDoc[])}
private ArrayList<MethodInfo> mAllSelfMethods = new ArrayList<MethodInfo>();
private ArrayList<MethodInfo> mAnnotationElements = new ArrayList<MethodInfo>(); // if this class is an annotation
private ArrayList<FieldInfo> mAllSelfFields = new ArrayList<FieldInfo>();
@@ -1498,8 +1699,9 @@
private ArrayList<FieldInfo> mFields;
private ArrayList<TypeInfo> mTypeParameters;
private ArrayList<MethodInfo> mHiddenMethods;
- private int mHidden = -1;
- private int mCheckLevel = -1;
+ private Boolean mHidden = null;
+ private Boolean mRemoved = null;
+ private Boolean mCheckLevel = null;
private String mReasonIncluded;
private ArrayList<MethodInfo> mNonWrittenConstructors;
private boolean mIsDeprecated;
@@ -1513,6 +1715,13 @@
// Resolutions
private ArrayList<Resolution> mResolutions;
+ private List<MethodInfo> mRemovedConstructors; // immutable after you set its value.
+ // @removed self methods that do not override any parent methods
+ private List<MethodInfo> mRemovedSelfMethods; // immutable after you set its value.
+ private List<MethodInfo> mRemovedMethods; // immutable after you set its value.
+ private List<FieldInfo> mRemovedSelfFields; // immutable after you set its value.
+ private List<FieldInfo> mRemovedEnumConstants; // immutable after you set its value.
+
/**
* Returns true if {@code cl} implements the interface {@code iface} either by either being that
* interface, implementing that interface or extending a type that implements the interface.
@@ -1798,7 +2007,7 @@
return consistent;
}
- // Find a superclass implementation of the given method.
+ // Find a superclass implementation of the given method based on the methods in mApiCheckMethods.
public static MethodInfo overriddenMethod(MethodInfo candidate, ClassInfo newClassObj) {
if (newClassObj == null) {
return null;
diff --git a/src/com/google/doclava/Comment.java b/src/com/google/doclava/Comment.java
index 70f4f30..c93cda7 100644
--- a/src/com/google/doclava/Comment.java
+++ b/src/com/google/doclava/Comment.java
@@ -458,37 +458,35 @@
}
public boolean isHidden() {
- if (mHidden != -1) {
- return mHidden != 0;
- } else {
- if (Doclava.checkLevel(Doclava.SHOW_HIDDEN)) {
- mHidden = 0;
- return false;
- }
- boolean b = mText.indexOf("@hide") >= 0 || mText.indexOf("@pending") >= 0;
- mHidden = b ? 1 : 0;
- return b;
+ if (mHidden == null) {
+ mHidden = !Doclava.checkLevel(Doclava.SHOW_HIDDEN) &&
+ (mText != null) && (mText.indexOf("@hide") >= 0 || mText.indexOf("@pending") >= 0);
}
+ return mHidden;
+ }
+
+ public boolean isRemoved() {
+ if (mRemoved == null) {
+ mRemoved = !Doclava.checkLevel(Doclava.SHOW_HIDDEN) &&
+ (mText != null) && (mText.indexOf("@removed") >= 0);
+ }
+
+ return mRemoved;
}
public boolean isDocOnly() {
- if (mDocOnly != -1) {
- return mDocOnly != 0;
- } else {
- boolean b = (mText != null) && (mText.indexOf("@doconly") >= 0);
- mDocOnly = b ? 1 : 0;
- return b;
+ if (mDocOnly == null) {
+ mDocOnly = (mText != null) && (mText.indexOf("@doconly") >= 0);
}
+ return mDocOnly;
}
-
+
public boolean isDeprecated() {
- if (mDeprecated != -1) {
- return mDeprecated != 0;
- } else {
- boolean b = (mText != null) && (mText.indexOf("@deprecated") >= 0);
- mDeprecated = b ? 1 : 0;
- return b;
+ if (mDeprecated == null) {
+ mDeprecated = (mText != null) && (mText.indexOf("@deprecated") >= 0);
}
+
+ return mDeprecated;
}
private void init() {
@@ -499,6 +497,7 @@
private void initImpl() {
isHidden();
+ isRemoved();
isDocOnly();
isDeprecated();
@@ -539,9 +538,10 @@
}
boolean mInitialized;
- int mHidden = -1;
- int mDocOnly = -1;
- int mDeprecated = -1;
+ Boolean mHidden = null;
+ Boolean mRemoved = null;
+ Boolean mDocOnly = null;
+ Boolean mDeprecated = null;
String mText;
ContainerInfo mBase;
SourcePositionInfo mPosition;
diff --git a/src/com/google/doclava/Converter.java b/src/com/google/doclava/Converter.java
index bdf6af5..e620bf3 100644
--- a/src/com/google/doclava/Converter.java
+++ b/src/com/google/doclava/Converter.java
@@ -41,6 +41,7 @@
import java.util.Arrays;
import java.util.HashMap;
import java.util.HashSet;
+import java.util.List;
public class Converter {
private static RootDoc root;
@@ -131,6 +132,18 @@
cl.setHiddenMethods(
new ArrayList<MethodInfo>(Arrays.asList(Converter.getHiddenMethods(c.methods(false)))));
+ cl.setRemovedMethods(
+ new ArrayList<MethodInfo>(Arrays.asList(Converter.getRemovedMethods(c.methods(false)))));
+
+ cl.setRemovedSelfMethods(
+ new ArrayList<MethodInfo>(Converter.convertAllMethods(c.methods(false))));
+ cl.setRemovedConstructors(
+ new ArrayList<MethodInfo>(Converter.convertAllMethods(c.constructors(false))));
+ cl.setRemovedSelfFields(
+ new ArrayList<FieldInfo>(Converter.convertAllFields(c.fields(false))));
+ cl.setRemovedEnumConstants(
+ new ArrayList<FieldInfo>(Converter.convertAllFields(c.enumConstants())));
+
cl.setNonWrittenConstructors(
new ArrayList<MethodInfo>(Arrays.asList(Converter.convertNonWrittenConstructors(
c.constructors(false)))));
@@ -288,81 +301,91 @@
private static MethodInfo[] getHiddenMethods(MethodDoc[] methods) {
if (methods == null) return null;
- ArrayList<MethodInfo> out = new ArrayList<MethodInfo>();
- int N = methods.length;
- for (int i = 0; i < N; i++) {
- MethodInfo m = Converter.obtainMethod(methods[i]);
- // System.out.println(m.toString() + ": ");
- // for (TypeInfo ti : m.getTypeParameters()){
- // if (ti.asClassInfo() != null){
- // System.out.println(" " +ti.asClassInfo().toString());
- // } else {
- // System.out.println(" null");
- // }
- // }
- if (m.isHidden()) {
- out.add(m);
+ ArrayList<MethodInfo> hiddenMethods = new ArrayList<MethodInfo>();
+ for (MethodDoc method : methods) {
+ MethodInfo methodInfo = Converter.obtainMethod(method);
+ if (methodInfo.isHidden()) {
+ hiddenMethods.add(methodInfo);
}
}
- return out.toArray(new MethodInfo[out.size()]);
+
+ return hiddenMethods.toArray(new MethodInfo[hiddenMethods.size()]);
+ }
+
+ // Gets the removed methods regardless of access levels
+ private static MethodInfo[] getRemovedMethods(MethodDoc[] methods) {
+ if (methods == null) return null;
+ ArrayList<MethodInfo> removedMethods = new ArrayList<MethodInfo>();
+ for (MethodDoc method : methods) {
+ MethodInfo methodInfo = Converter.obtainMethod(method);
+ if (methodInfo.isRemoved()) {
+ removedMethods.add(methodInfo);
+ }
+ }
+
+ return removedMethods.toArray(new MethodInfo[removedMethods.size()]);
}
/**
- * Convert MethodDoc[] into MethodInfo[]. Also filters according to the -private, -public option,
- * because the filtering doesn't seem to be working in the ClassDoc.constructors(boolean) call.
+ * Converts FieldDoc[] into List<FieldInfo>. No filtering is done.
*/
- private static MethodInfo[] convertMethods(MethodDoc[] methods) {
- if (methods == null) return null;
- ArrayList<MethodInfo> out = new ArrayList<MethodInfo>();
- int N = methods.length;
- for (int i = 0; i < N; i++) {
- MethodInfo m = Converter.obtainMethod(methods[i]);
- // System.out.println(m.toString() + ": ");
- // for (TypeInfo ti : m.getTypeParameters()){
- // if (ti.asClassInfo() != null){
- // System.out.println(" " +ti.asClassInfo().toString());
- // } else {
- // System.out.println(" null");
- // }
- // }
- if (m.checkLevel()) {
- out.add(m);
- }
+ private static List<FieldInfo> convertAllFields(FieldDoc[] fields) {
+ if (fields == null) return null;
+ List<FieldInfo> allFields = new ArrayList<FieldInfo>();
+
+ for (FieldDoc field : fields) {
+ FieldInfo fieldInfo = Converter.obtainField(field);
+ allFields.add(fieldInfo);
}
- return out.toArray(new MethodInfo[out.size()]);
+
+ return allFields;
}
- private static MethodInfo[] convertMethods(ConstructorDoc[] methods) {
+ /**
+ * Converts ExecutableMemberDoc[] into List<MethodInfo>. No filtering is done.
+ */
+ private static List<MethodInfo> convertAllMethods(ExecutableMemberDoc[] methods) {
if (methods == null) return null;
- ArrayList<MethodInfo> out = new ArrayList<MethodInfo>();
- int N = methods.length;
- for (int i = 0; i < N; i++) {
- MethodInfo m = Converter.obtainMethod(methods[i]);
- if (m.checkLevel()) {
- out.add(m);
+ List<MethodInfo> allMethods = new ArrayList<MethodInfo>();
+ for (ExecutableMemberDoc method : methods) {
+ MethodInfo methodInfo = Converter.obtainMethod(method);
+ allMethods.add(methodInfo);
+ }
+ return allMethods;
+ }
+
+ /**
+ * Convert MethodDoc[] or ConstructorDoc[] into MethodInfo[].
+ * Also filters according to the -private, -public option,
+ * because the filtering doesn't seem to be working in the ClassDoc.constructors(boolean) call.
+ */
+ private static MethodInfo[] convertMethods(ExecutableMemberDoc[] methods) {
+ if (methods == null) return null;
+ List<MethodInfo> filteredMethods = new ArrayList<MethodInfo>();
+ for (ExecutableMemberDoc method : methods) {
+ MethodInfo methodInfo = Converter.obtainMethod(method);
+ if (methodInfo.checkLevel()) {
+ filteredMethods.add(methodInfo);
}
}
- return out.toArray(new MethodInfo[out.size()]);
+
+ return filteredMethods.toArray(new MethodInfo[filteredMethods.size()]);
}
private static MethodInfo[] convertNonWrittenConstructors(ConstructorDoc[] methods) {
if (methods == null) return null;
- ArrayList<MethodInfo> out = new ArrayList<MethodInfo>();
- int N = methods.length;
- for (int i = 0; i < N; i++) {
- MethodInfo m = Converter.obtainMethod(methods[i]);
- if (!m.checkLevel()) {
- out.add(m);
+ ArrayList<MethodInfo> ctors = new ArrayList<MethodInfo>();
+ for (ConstructorDoc method : methods) {
+ MethodInfo methodInfo = Converter.obtainMethod(method);
+ if (!methodInfo.checkLevel()) {
+ ctors.add(methodInfo);
}
}
- return out.toArray(new MethodInfo[out.size()]);
+
+ return ctors.toArray(new MethodInfo[ctors.size()]);
}
- private static MethodInfo obtainMethod(MethodDoc o) {
- return (MethodInfo) mMethods.obtain(o);
- }
-
- private static MethodInfo obtainMethod(ConstructorDoc o) {
+ private static <E extends ExecutableMemberDoc> MethodInfo obtainMethod(E o) {
return (MethodInfo) mMethods.obtain(o);
}
@@ -559,11 +582,11 @@
return keyString;
}
};
-
+
public static TypeInfo obtainTypeFromString(String type) {
return (TypeInfo) mTypesFromString.obtain(type);
}
-
+
private static final Cache mTypesFromString = new Cache() {
@Override
protected Object make(Object o) {
@@ -573,7 +596,7 @@
@Override
protected void made(Object o, Object r) {
-
+
}
@Override
diff --git a/src/com/google/doclava/DocFile.java b/src/com/google/doclava/DocFile.java
index e28ad59..c27c82a 100644
--- a/src/com/google/doclava/DocFile.java
+++ b/src/com/google/doclava/DocFile.java
@@ -55,19 +55,24 @@
"ru", "zh-cn", "zh-tw", "pt-br"};
public static String getPathRoot(String filename) {
- //look for a valid lang string in the file path. If found,
- //snip the intl/lang from the path.
- for (String t : DEVSITE_VALID_LANGS) {
- int langStart = filename.indexOf("/" + t + "/");
- if (langStart > -1) {
- int langEnd = filename.indexOf("/", langStart + 1);
- filename = filename.substring(langEnd + 1);
- break;
+ String[] stripStr = filename.split("\\/");
+ String outFrag = stripStr[0];
+ if (stripStr.length > 0) {
+ for (String t : DEVSITE_VALID_LANGS) {
+ if (stripStr[0].equals("intl")) {
+ if (stripStr[1].equals(t)) {
+ outFrag = stripStr[2];
+ break;
+ }
+ } else if (stripStr[0].equals(t)) {
+ outFrag = stripStr[1];
+ break;
+ }
}
}
- return filename;
+ return outFrag;
}
-
+
public static Data getPageMetadata (String docfile, Data hdf) {
//utility method for extracting metadata without generating file output.
if (hdf == null) {
@@ -188,7 +193,6 @@
hdf.setValue("page.type", "design");
} else if (filename.indexOf("develop") == 0) {
hdf.setValue("develop", "true");
- hdf.setValue("page.type", "develop");
} else if (filename.indexOf("guide") == 0) {
hdf.setValue("guide", "true");
hdf.setValue("page.type", "guide");
@@ -209,21 +213,6 @@
} else if (filename.indexOf("distribute") == 0) {
hdf.setValue("distribute", "true");
hdf.setValue("page.type", "distribute");
- if (filename.indexOf("distribute/googleplay") == 0) {
- hdf.setValue("googleplay", "true");
- } else if (filename.indexOf("distribute/essentials") == 0) {
- hdf.setValue("essentials", "true");
- } else if (filename.indexOf("distribute/users") == 0) {
- hdf.setValue("users", "true");
- } else if (filename.indexOf("distribute/engage") == 0) {
- hdf.setValue("engage", "true");
- } else if (filename.indexOf("distribute/monetize") == 0) {
- hdf.setValue("monetize", "true");
- } else if (filename.indexOf("distribute/tools") == 0) {
- hdf.setValue("disttools", "true");
- } else if (filename.indexOf("distribute/stories") == 0) {
- hdf.setValue("stories", "true");
- }
} else if (filename.indexOf("about") == 0) {
hdf.setValue("about", "true");
hdf.setValue("page.type", "about");
@@ -243,9 +232,6 @@
} else if (filename.indexOf("wear") == 0) {
hdf.setValue("wear", "true");
}
- //set metadata for this file in jd_lists_unified
- PageMetadata.setPageMetadata(docfile, relative, outfile, hdf, Doclava.sTaglist);
-
if (fromTemplate.equals("sdk")) {
ClearPage.write(hdf, "sdkpage.cs", outfile);
} else {
diff --git a/src/com/google/doclava/DocInfo.java b/src/com/google/doclava/DocInfo.java
index 714beb8..d8a1961 100644
--- a/src/com/google/doclava/DocInfo.java
+++ b/src/com/google/doclava/DocInfo.java
@@ -32,11 +32,30 @@
* The relative path to a web page representing this item.
*/
public abstract String htmlPage();
-
+
+ /**
+ * @return true if the element has never been a part of public API
+ */
public boolean isHidden() {
return comment().isHidden();
}
+ /**
+ * @return true if the element was once a part of public API, now removed.
+ */
+ public boolean isRemoved() {
+ return comment().isRemoved();
+ }
+
+ /**
+ * Hidden and removed elements should not be appear in api.txt files, nor
+ * should they appear in the java doc.
+ * @return true if the element is either hidden or removed.
+ */
+ public boolean isHiddenOrRemoved() {
+ return isHidden() || isRemoved();
+ }
+
public boolean isDocOnly() {
return comment().isDocOnly();
}
@@ -84,7 +103,7 @@
public String getSince() {
return mSince;
}
-
+
public void setDeprecatedSince(String since) {
mDeprecatedSince = since;
}
@@ -100,11 +119,11 @@
public final void addFederatedReference(FederatedSite source) {
mFederatedReferences.add(source);
}
-
+
public final Set<FederatedSite> getFederatedReferences() {
return mFederatedReferences;
}
-
+
public final void setFederatedReferences(Data data, String base) {
int pos = 0;
for (FederatedSite source : getFederatedReferences()) {
diff --git a/src/com/google/doclava/Doclava.java b/src/com/google/doclava/Doclava.java
index a96b91c..c947d1e 100644
--- a/src/com/google/doclava/Doclava.java
+++ b/src/com/google/doclava/Doclava.java
@@ -66,8 +66,6 @@
public static int showLevel = SHOW_PROTECTED;
public static final boolean SORT_BY_NAV_GROUPS = true;
- /* Debug output for PageMetadata, format urls from site root */
- public static boolean META_DBG=false;
public static String outputPathBase = "/";
public static ArrayList<String> inputPathHtmlDirs = new ArrayList<String>();
@@ -116,7 +114,6 @@
public static boolean checkLevel(boolean pub, boolean prot, boolean pkgp, boolean priv,
boolean hidden) {
- int level = 0;
if (hidden && !checkLevel(SHOW_HIDDEN)) {
return false;
}
@@ -150,6 +147,7 @@
// Create the dependency graph for the stubs directory
boolean offlineMode = false;
String apiFile = null;
+ String removedApiFile = null;
String debugStubsFile = "";
HashSet<String> stubPackages = null;
ArrayList<String> knownTagsFiles = new ArrayList<String>();
@@ -236,7 +234,10 @@
sdkValuePath = a[1];
} else if (a[0].equals("-api")) {
apiFile = a[1];
- } else if (a[0].equals("-nodocs")) {
+ } else if (a[0].equals("-removedApi")) {
+ removedApiFile = a[1];
+ }
+ else if (a[0].equals("-nodocs")) {
generateDocs = false;
} else if (a[0].equals("-nodefaultassets")) {
includeDefaultAssets = false;
@@ -246,8 +247,6 @@
sinceTagger.addVersion(a[1], a[2]);
} else if (a[0].equals("-offlinemode")) {
offlineMode = true;
- } else if (a[0].equals("-metadataDebug")) {
- META_DBG = true;
} else if (a[0].equals("-federate")) {
try {
String name = a[1];
@@ -317,10 +316,10 @@
TodoFile.writeTodoFile(todoFile);
}
- if (samplesRef) {
+ if (samplesRef) {
// always write samples without offlineMode behaviors
- writeSamples(false, sampleCodes, SORT_BY_NAV_GROUPS);
- }
+ writeSamples(false, sampleCodes, SORT_BY_NAV_GROUPS);
+ }
// HTML2 Pages -- Generate Pages from optional secondary dir
if (!inputPathHtmlDir2.isEmpty()) {
@@ -340,7 +339,7 @@
}
writeAssets();
-
+
// Navigation tree
String refPrefix = new String();
if(gmsRef){
@@ -359,25 +358,25 @@
writePackages(javadocDir + refPrefix + "packages" + htmlExtension);
// Classes
- writeClassLists();
- writeClasses();
- writeHierarchy();
+ writeClassLists();
+ writeClasses();
+ writeHierarchy();
// writeKeywords();
// Lists for JavaScript
- writeLists();
+ writeLists();
if (keepListFile != null) {
writeKeepList(keepListFile);
}
// Index page
- writeIndex();
+ writeIndex();
- Proofread.finishProofread(proofreadFile);
+ Proofread.finishProofread(proofreadFile);
- if (sdkValuePath != null) {
- writeSdkValues(sdkValuePath);
- }
+ if (sdkValuePath != null) {
+ writeSdkValues(sdkValuePath);
+ }
// Write metadata for all processed files to jd_lists_unified.js in out dir
if (!sTaglist.isEmpty()) {
PageMetadata.WriteList(sTaglist);
@@ -385,8 +384,8 @@
}
// Stubs
- if (stubsDir != null || apiFile != null || proguardFile != null) {
- Stubs.writeStubsAndApi(stubsDir, apiFile, proguardFile, stubPackages);
+ if (stubsDir != null || apiFile != null || proguardFile != null || removedApiFile != null) {
+ Stubs.writeStubsAndApi(stubsDir, apiFile, proguardFile, removedApiFile, stubPackages);
}
Errors.printErrors();
@@ -613,6 +612,9 @@
if (option.equals("-api")) {
return 2;
}
+ if (option.equals("-removedApi")) {
+ return 2;
+ }
if (option.equals("-nodocs")) {
return 1;
}
@@ -648,9 +650,6 @@
gcmRef = true;
return 1;
}
- if (option.equals("-metadataDebug")) {
- return 1;
- }
return 0;
}
public static boolean validOptions(String[][] options, DocErrorReporter r) {
@@ -700,13 +699,13 @@
for (String s : sorted.keySet()) {
PackageInfo pkg = sorted.get(s);
- if (pkg.isHidden()) {
+ if (pkg.isHiddenOrRemoved()) {
continue;
}
- Boolean allHidden = true;
+ boolean allHiddenOrRemoved = true;
int pass = 0;
ClassInfo[] classesToCheck = null;
- while (pass < 5) {
+ while (pass < 6) {
switch (pass) {
case 0:
classesToCheck = pkg.ordinaryClasses();
@@ -723,22 +722,25 @@
case 4:
classesToCheck = pkg.interfaces();
break;
+ case 5:
+ classesToCheck = pkg.annotations();
+ break;
default:
System.err.println("Error reading package: " + pkg.name());
break;
}
for (ClassInfo cl : classesToCheck) {
- if (!cl.isHidden()) {
- allHidden = false;
+ if (!cl.isHiddenOrRemoved()) {
+ allHiddenOrRemoved = false;
break;
}
}
- if (!allHidden) {
+ if (!allHiddenOrRemoved) {
break;
}
pass++;
}
- if (allHidden) {
+ if (allHiddenOrRemoved) {
continue;
}
if(gmsRef){
@@ -775,6 +777,11 @@
Data data = makeHDF();
String filename = templ.substring(0, len - 3) + htmlExtension;
DocFile.writePage(f.getAbsolutePath(), relative, filename, data);
+ String[] sections = relative.split("\\/");
+ boolean isIntl = ((sections.length > 0) && (sections[0].equals("intl")));
+ //if (!isIntl) {
+ PageMetadata.setPageMetadata(f, relative, filename, data, sTaglist);
+ //}
} else if(!f.getName().equals(".DS_Store")){
Data data = makeHDF();
String hdfValue = data.getValue("sac") == null ? "" : data.getValue("sac");
@@ -842,7 +849,7 @@
SortedMap<String, Object> sorted = new TreeMap<String, Object>();
for (ClassInfo cl : classes) {
- if (cl.isHidden()) {
+ if (cl.isHiddenOrRemoved()) {
continue;
}
sorted.put(cl.qualifiedName(), cl);
@@ -911,7 +918,8 @@
// If it's a .jd file we want to process
if (len > 3 && ".jd".equals(templ.substring(len - 3))) {
// remove the directories below the site root
- String webPath = filePath.substring(filePath.indexOf("docs/html/") + 10, filePath.length());
+ String webPath = filePath.substring(filePath.indexOf("docs/html/") + 10,
+ filePath.length());
// replace .jd with .html
webPath = webPath.substring(0, webPath.length() - 3) + htmlExtension;
// Parse the .jd file for properties data at top of page
@@ -1024,7 +1032,7 @@
// If a class is public and not hidden, then it and everything it derives
// from cannot be stripped. Otherwise we can strip it.
for (ClassInfo cl : all) {
- if (cl.isPublic() && !cl.isHidden()) {
+ if (cl.isPublic() && !cl.isHiddenOrRemoved()) {
cantStripThis(cl, notStrippable);
}
}
@@ -1068,13 +1076,14 @@
for (String s : sorted.keySet()) {
PackageInfo pkg = sorted.get(s);
- if (pkg.isHidden()) {
+ if (pkg.isHiddenOrRemoved()) {
continue;
}
- Boolean allHidden = true;
+
+ boolean allHiddenOrRemoved = true;
int pass = 0;
ClassInfo[] classesToCheck = null;
- while (pass < 5) {
+ while (pass < 6) {
switch (pass) {
case 0:
classesToCheck = pkg.ordinaryClasses();
@@ -1091,22 +1100,25 @@
case 4:
classesToCheck = pkg.interfaces();
break;
+ case 5:
+ classesToCheck = pkg.annotations();
+ break;
default:
System.err.println("Error reading package: " + pkg.name());
break;
}
for (ClassInfo cl : classesToCheck) {
- if (!cl.isHidden()) {
- allHidden = false;
+ if (!cl.isHiddenOrRemoved()) {
+ allHiddenOrRemoved = false;
break;
}
}
- if (!allHidden) {
+ if (!allHiddenOrRemoved) {
break;
}
pass++;
}
- if (allHidden) {
+ if (allHiddenOrRemoved) {
continue;
}
@@ -1153,6 +1165,7 @@
data.setValue("package.descr", "...description...");
pkg.setFederatedReferences(data, "package");
+ makeClassListHDF(data, "package.annotations", ClassInfo.sortByName(pkg.annotations()));
makeClassListHDF(data, "package.interfaces", ClassInfo.sortByName(pkg.interfaces()));
makeClassListHDF(data, "package.classes", ClassInfo.sortByName(pkg.ordinaryClasses()));
makeClassListHDF(data, "package.enums", ClassInfo.sortByName(pkg.enums()));
@@ -1172,7 +1185,8 @@
int i;
Data data = makePackageHDF();
- ClassInfo[] classes = PackageInfo.filterHidden(Converter.convertClasses(root.classes()));
+ ClassInfo[] classes = PackageInfo.filterHiddenAndRemoved(
+ Converter.convertClasses(root.classes()));
if (classes.length == 0) {
return;
}
@@ -1226,7 +1240,7 @@
* public static void writeKeywords() { ArrayList<KeywordEntry> keywords = new
* ArrayList<KeywordEntry>();
*
- * ClassInfo[] classes = PackageInfo.filterHidden(Converter.convertClasses(root.classes()));
+ * ClassInfo[] classes = PackageInfo.filterHiddenAndRemoved(Converter.convertClasses(root.classes()));
*
* for (ClassInfo cl: classes) { cl.makeKeywordEntries(keywords); }
*
@@ -1245,7 +1259,7 @@
ClassInfo[] classes = Converter.rootClasses();
ArrayList<ClassInfo> info = new ArrayList<ClassInfo>();
for (ClassInfo cl : classes) {
- if (!cl.isHidden()) {
+ if (!cl.isHiddenOrRemoved()) {
info.add(cl);
}
}
@@ -1260,7 +1274,7 @@
for (ClassInfo cl : classes) {
Data data = makePackageHDF();
- if (!cl.isHidden()) {
+ if (!cl.isHiddenOrRemoved()) {
writeClass(cl, data);
}
}
@@ -1277,7 +1291,7 @@
public static void makeClassListHDF(Data data, String base, ClassInfo[] classes) {
for (int i = 0; i < classes.length; i++) {
ClassInfo cl = classes[i];
- if (!cl.isHidden()) {
+ if (!cl.isHiddenOrRemoved()) {
cl.makeShortDescrHDF(data, base + "." + i);
}
}
@@ -1313,20 +1327,21 @@
}
/**
- * Returns true if the given element has an @hide or @pending annotation.
+ * Returns true if the given element has an @hide, @removed or @pending annotation.
*/
- private static boolean hasHideAnnotation(Doc doc) {
+ private static boolean hasHideOrRemovedAnnotation(Doc doc) {
String comment = doc.getRawCommentText();
- return comment.indexOf("@hide") != -1 || comment.indexOf("@pending") != -1;
+ return comment.indexOf("@hide") != -1 || comment.indexOf("@pending") != -1 ||
+ comment.indexOf("@removed") != -1;
}
/**
* Returns true if the given element is hidden.
*/
- private static boolean isHidden(Doc doc) {
+ private static boolean isHiddenOrRemoved(Doc doc) {
// Methods, fields, constructors.
if (doc instanceof MemberDoc) {
- return hasHideAnnotation(doc);
+ return hasHideOrRemovedAnnotation(doc);
}
// Classes, interfaces, enums, annotation types.
@@ -1334,7 +1349,7 @@
ClassDoc classDoc = (ClassDoc) doc;
// Check the containing package.
- if (hasHideAnnotation(classDoc.containingPackage())) {
+ if (hasHideOrRemovedAnnotation(classDoc.containingPackage())) {
return true;
}
@@ -1342,7 +1357,7 @@
// nested class.
ClassDoc current = classDoc;
do {
- if (hasHideAnnotation(current)) {
+ if (hasHideOrRemovedAnnotation(current)) {
return true;
}
@@ -1354,9 +1369,9 @@
}
/**
- * Filters out hidden elements.
+ * Filters out hidden and removed elements.
*/
- private static Object filterHidden(Object o, Class<?> expected) {
+ private static Object filterHiddenAndRemoved(Object o, Class<?> expected) {
if (o == null) {
return null;
}
@@ -1371,10 +1386,10 @@
Object[] array = (Object[]) o;
List<Object> list = new ArrayList<Object>(array.length);
for (Object entry : array) {
- if ((entry instanceof Doc) && isHidden((Doc) entry)) {
+ if ((entry instanceof Doc) && isHiddenOrRemoved((Doc) entry)) {
continue;
}
- list.add(filterHidden(entry, componentType));
+ list.add(filterHiddenAndRemoved(entry, componentType));
}
return list.toArray((Object[]) Array.newInstance(componentType, list.size()));
} else {
@@ -1412,7 +1427,7 @@
}
try {
- return filterHidden(method.invoke(target, args), method.getReturnType());
+ return filterHiddenAndRemoved(method.invoke(target, args), method.getReturnType());
} catch (InvocationTargetException e) {
throw e.getTargetException();
}
@@ -1492,7 +1507,7 @@
// Now check the class for @Widget or if its in the android.widget package
// (unless the class is hidden or abstract, or non public)
- if (clazz.isHidden() == false && clazz.isPublic() && clazz.isAbstract() == false) {
+ if (clazz.isHiddenOrRemoved() == false && clazz.isPublic() && clazz.isAbstract() == false) {
boolean annotated = false;
ArrayList<AnnotationInstanceInfo> annotations = clazz.annotations();
if (!annotations.isEmpty()) {
@@ -1760,5 +1775,5 @@
return false;
}
}
-
-}
\ No newline at end of file
+
+}
diff --git a/src/com/google/doclava/Hierarchy.java b/src/com/google/doclava/Hierarchy.java
index 0887b63..0fddf9a 100755
--- a/src/com/google/doclava/Hierarchy.java
+++ b/src/com/google/doclava/Hierarchy.java
@@ -88,7 +88,7 @@
}
private static boolean exists(ClassInfo cl) {
- return cl != null && !cl.isHidden() && cl.isIncluded();
+ return cl != null && !cl.isHiddenOrRemoved() && cl.isIncluded();
}
private static void recurse(HashMap<String, TreeSet<String>> nodes, String name, Data hdf,
diff --git a/src/com/google/doclava/LinkReference.java b/src/com/google/doclava/LinkReference.java
index 816bdb1..dfece8e 100644
--- a/src/com/google/doclava/LinkReference.java
+++ b/src/com/google/doclava/LinkReference.java
@@ -59,7 +59,7 @@
public boolean good;
/**
- * regex pattern to use when matching explicit 'a href' reference text
+ * regex pattern to use when matching explicit "<a href" reference text
*/
private static final Pattern HREF_PATTERN =
Pattern.compile("^<a href=\"([^\"]*)\">([^<]*)</a>[ \n\r\t]*$", Pattern.CASE_INSENSITIVE);
diff --git a/src/com/google/doclava/MemberInfo.java b/src/com/google/doclava/MemberInfo.java
index e5cc7a2..800edba 100644
--- a/src/com/google/doclava/MemberInfo.java
+++ b/src/com/google/doclava/MemberInfo.java
@@ -54,6 +54,23 @@
return super.isHidden();
}
+ @Override
+ public boolean isRemoved() {
+ if (mAnnotations != null) {
+ for (AnnotationInstanceInfo info : mAnnotations) {
+ if (Doclava.showAnnotations.contains(info.type().qualifiedName())) {
+ return false;
+ }
+ }
+ }
+ return super.isRemoved();
+ }
+
+ @Override
+ public boolean isHiddenOrRemoved() {
+ return isHidden() || isRemoved();
+ }
+
public String anchor() {
if (mSignature != null) {
return mName + mSignature;
@@ -101,7 +118,7 @@
public boolean isPrivate() {
return mIsPrivate;
}
-
+
public String scope() {
if (isPublic()) {
return "public";
@@ -134,7 +151,8 @@
}
public boolean checkLevel() {
- return Doclava.checkLevel(mIsPublic, mIsProtected, mIsPackagePrivate, mIsPrivate, isHidden());
+ return Doclava.checkLevel(mIsPublic, mIsProtected, mIsPackagePrivate, mIsPrivate,
+ isHiddenOrRemoved());
}
public String kind() {
diff --git a/src/com/google/doclava/NavTree.java b/src/com/google/doclava/NavTree.java
index aa02d7c..cc4f43f 100644
--- a/src/com/google/doclava/NavTree.java
+++ b/src/com/google/doclava/NavTree.java
@@ -64,7 +64,7 @@
SortedMap<String, Object> sorted = new TreeMap<String, Object>();
for (ClassInfo cl : classes) {
- if (cl.isHidden()) {
+ if (cl.isHiddenOrRemoved()) {
continue;
}
sorted.put(cl.qualifiedName(), cl);
@@ -133,6 +133,7 @@
private static Node makePackageNode(PackageInfo pkg) {
List<Node> children = new ArrayList<Node>();
+ addClassNodes(children, "Annotations", pkg.annotations());
addClassNodes(children, "Interfaces", pkg.interfaces());
addClassNodes(children, "Classes", pkg.ordinaryClasses());
addClassNodes(children, "Enums", pkg.enums());
diff --git a/src/com/google/doclava/PackageInfo.java b/src/com/google/doclava/PackageInfo.java
index 65a9639..e997b27 100644
--- a/src/com/google/doclava/PackageInfo.java
+++ b/src/com/google/doclava/PackageInfo.java
@@ -61,6 +61,7 @@
}
private void initializeMaps() {
+ mAnnotationsMap = new HashMap<String, ClassInfo>();
mInterfacesMap = new HashMap<String, ClassInfo>();
mOrdinaryClassesMap = new HashMap<String, ClassInfo>();
mEnumsMap = new HashMap<String, ClassInfo>();
@@ -83,13 +84,82 @@
@Override
public boolean isHidden() {
- return comment().isHidden();
+ if (mHidden == null) {
+ if (hasHideComment()) {
+ // We change the hidden value of the package if a class wants to be not hidden.
+ ClassInfo[][] types = new ClassInfo[][] { annotations(), interfaces(), ordinaryClasses(),
+ enums(), exceptions() };
+ for (ClassInfo[] type : types) {
+ if (type != null) {
+ for (ClassInfo c : type) {
+ if (c.hasShowAnnotation()) {
+ mHidden = false;
+ return false;
+ }
+ }
+ }
+ }
+ mHidden = true;
+ } else {
+ mHidden = false;
+ }
+ }
+ return mHidden;
+ }
+
+ @Override
+ public boolean isRemoved() {
+ if (mRemoved == null) {
+ if (hasRemovedComment()) {
+ // We change the removed value of the package if a class wants to be not hidden.
+ ClassInfo[][] types = new ClassInfo[][] { annotations(), interfaces(), ordinaryClasses(),
+ enums(), exceptions() };
+ for (ClassInfo[] type : types) {
+ if (type != null) {
+ for (ClassInfo c : type) {
+ if (c.hasShowAnnotation()) {
+ mRemoved = false;
+ return false;
+ }
+ }
+ }
+ }
+ mRemoved = true;
+ } else {
+ mRemoved = false;
+ }
+ }
+
+ return mRemoved;
+ }
+
+ @Override
+ public boolean isHiddenOrRemoved() {
+ return isHidden() || isRemoved();
+ }
+
+ /**
+ * Used by ClassInfo to determine packages default visability before annoations.
+ */
+ public boolean hasHideComment() {
+ if (mHiddenByComment == null) {
+ mHiddenByComment = comment().isHidden();
+ }
+ return mHiddenByComment;
+ }
+
+ public boolean hasRemovedComment() {
+ if (mRemovedByComment == null) {
+ mRemovedByComment = comment().isRemoved();
+ }
+
+ return mRemovedByComment;
}
public boolean checkLevel() {
// TODO should return false if all classes are hidden but the package isn't.
// We don't have this so I'm not doing it now.
- return !isHidden();
+ return !isHiddenOrRemoved();
}
public String name() {
@@ -108,11 +178,15 @@
return comment().briefTags();
}
- public static ClassInfo[] filterHidden(ClassInfo[] classes) {
+ /**
+ * @param classes the Array of ClassInfo to be filtered
+ * @return an Array of ClassInfo without any hidden or removed classes
+ */
+ public static ClassInfo[] filterHiddenAndRemoved(ClassInfo[] classes) {
ArrayList<ClassInfo> out = new ArrayList<ClassInfo>();
for (ClassInfo cl : classes) {
- if (!cl.isHidden()) {
+ if (!cl.isHiddenOrRemoved()) {
out.add(cl);
}
}
@@ -130,6 +204,7 @@
public void makeClassLinkListHDF(Data data, String base) {
makeLink(data, base);
+ ClassInfo.makeLinkListHDF(data, base + ".annotations", annotations());
ClassInfo.makeLinkListHDF(data, base + ".interfaces", interfaces());
ClassInfo.makeLinkListHDF(data, base + ".classes", ordinaryClasses());
ClassInfo.makeLinkListHDF(data, base + ".enums", enums());
@@ -138,10 +213,20 @@
data.setValue(base + ".since", getSince());
}
+ public ClassInfo[] annotations() {
+ if (mAnnotations == null) {
+ mAnnotations =
+ ClassInfo.sortByName(filterHiddenAndRemoved(
+ Converter.convertClasses(mPackage.annotationTypes())));
+ }
+ return mAnnotations;
+ }
+
public ClassInfo[] interfaces() {
if (mInterfaces == null) {
mInterfaces =
- ClassInfo.sortByName(filterHidden(Converter.convertClasses(mPackage.interfaces())));
+ ClassInfo.sortByName(filterHiddenAndRemoved(
+ Converter.convertClasses(mPackage.interfaces())));
}
return mInterfaces;
}
@@ -149,14 +234,16 @@
public ClassInfo[] ordinaryClasses() {
if (mOrdinaryClasses == null) {
mOrdinaryClasses =
- ClassInfo.sortByName(filterHidden(Converter.convertClasses(mPackage.ordinaryClasses())));
+ ClassInfo.sortByName(filterHiddenAndRemoved(
+ Converter.convertClasses(mPackage.ordinaryClasses())));
}
return mOrdinaryClasses;
}
public ClassInfo[] enums() {
if (mEnums == null) {
- mEnums = ClassInfo.sortByName(filterHidden(Converter.convertClasses(mPackage.enums())));
+ mEnums = ClassInfo.sortByName(filterHiddenAndRemoved(
+ Converter.convertClasses(mPackage.enums())));
}
return mEnums;
}
@@ -164,14 +251,16 @@
public ClassInfo[] exceptions() {
if (mExceptions == null) {
mExceptions =
- ClassInfo.sortByName(filterHidden(Converter.convertClasses(mPackage.exceptions())));
+ ClassInfo.sortByName(filterHiddenAndRemoved(
+ Converter.convertClasses(mPackage.exceptions())));
}
return mExceptions;
}
public ClassInfo[] errors() {
if (mErrors == null) {
- mErrors = ClassInfo.sortByName(filterHidden(Converter.convertClasses(mPackage.errors())));
+ mErrors = ClassInfo.sortByName(filterHiddenAndRemoved(
+ Converter.convertClasses(mPackage.errors())));
}
return mErrors;
}
@@ -190,15 +279,21 @@
return mName.hashCode();
}
+ private Boolean mHidden = null;
+ private Boolean mHiddenByComment = null;
+ private Boolean mRemoved = null;
+ private Boolean mRemovedByComment = null;
private String mName;
private PackageDoc mPackage;
private ApiInfo mContainingApi;
+ private ClassInfo[] mAnnotations;
private ClassInfo[] mInterfaces;
private ClassInfo[] mOrdinaryClasses;
private ClassInfo[] mEnums;
private ClassInfo[] mExceptions;
private ClassInfo[] mErrors;
+ private HashMap<String, ClassInfo> mAnnotationsMap;
private HashMap<String, ClassInfo> mInterfacesMap;
private HashMap<String, ClassInfo> mOrdinaryClassesMap;
private HashMap<String, ClassInfo> mEnumsMap;
@@ -230,10 +325,24 @@
if (cls != null) {
return cls;
}
+ cls = mAnnotationsMap.get(className);
+
+ if (cls != null) {
+ return cls;
+ }
return mErrorsMap.get(className);
}
+ public void addAnnotation(ClassInfo cls) {
+ cls.setPackage(this);
+ mAnnotationsMap.put(cls.name(), cls);
+ }
+
+ public ClassInfo getAnnotation(String annotationName) {
+ return mAnnotationsMap.get(annotationName);
+ }
+
public void addInterface(ClassInfo cls) {
cls.setPackage(this);
mInterfacesMap.put(cls.name(), cls);
diff --git a/src/com/google/doclava/PageMetadata.java b/src/com/google/doclava/PageMetadata.java
index 360ae84..c22ac0f 100644
--- a/src/com/google/doclava/PageMetadata.java
+++ b/src/com/google/doclava/PageMetadata.java
@@ -16,8 +16,6 @@
package com.google.doclava;
-import java.io.*;
-import java.text.BreakIterator;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
@@ -28,24 +26,6 @@
import com.google.clearsilver.jsilver.data.Data;
-import org.ccil.cowan.tagsoup.*;
-import org.xml.sax.XMLReader;
-import org.xml.sax.InputSource;
-import org.xml.sax.Attributes;
-import org.xml.sax.helpers.DefaultHandler;
-
-import org.w3c.dom.Node;
-import org.w3c.dom.NodeList;
-
-import javax.xml.transform.dom.DOMResult;
-import javax.xml.transform.sax.SAXSource;
-import javax.xml.transform.Transformer;
-import javax.xml.transform.TransformerFactory;
-import javax.xml.xpath.XPath;
-import javax.xml.xpath.XPathConstants;
-import javax.xml.xpath.XPathExpression;
-import javax.xml.xpath.XPathFactory;
-
/**
* Metadata associated with a specific documentation page. Extracts
* metadata based on the page's declared hdf vars (meta.tags and others)
@@ -63,13 +43,6 @@
String mTagList;
static boolean sLowercaseTags = true;
static boolean sLowercaseKeywords = true;
- //static String linkPrefix = (Doclava.META_DBG) ? "/" : "http://developer.android.com/";
- /**
- * regex pattern to match javadoc @link and similar tags. Extracts
- * root symbol to $1.
- */
- private static final Pattern JD_TAG_PATTERN =
- Pattern.compile("\\{@.*?[\\s\\.\\#]([A-Za-z\\(\\)\\d_]+)(?=\u007D)\u007D");
public PageMetadata(File source, String dest, List<Node> taglist) {
mSource = source;
@@ -114,152 +87,32 @@
* are normalized. Unsupported metadata fields are ignored. See
* Node for supported metadata fields and methods for accessing values.
*
- * @param docfile The file from which to extract metadata.
+ * @param file The file from which to extract metadata.
* @param dest The output path for the file, used to set link to page.
* @param filename The file from which to extract metadata.
* @param hdf Data object in which to store the metadata values.
* @param tagList The file from which to extract metadata.
+ * @return tagList with new node added.
*/
- public static void setPageMetadata(String docfile, String dest, String filename,
+ public static List<Node> setPageMetadata(File file, String dest, String filename,
Data hdf, List<Node> tagList) {
//exclude this page if author does not want it included
boolean excludeNode = "true".equals(hdf.getValue("excludeFromSuggestions",""));
-
- //check whether summary and image exist and if not, get them from itemprop/markup
- Boolean needsSummary = "".equals(hdf.getValue("page.metaDescription", ""));
- Boolean needsImage = "".equals(hdf.getValue("page.image", ""));
- if ((needsSummary) || (needsImage)) {
- //try to extract the metadata from itemprop and markup
- inferMetadata(docfile, hdf, needsSummary, needsImage);
- }
-
- //extract available metadata and set it in a node
if (!excludeNode) {
Node pageMeta = new Node.Builder().build();
pageMeta.setLabel(getTitleNormalized(hdf, "page.title"));
pageMeta.setTitleFriendly(hdf.getValue("page.titleFriendly",""));
- pageMeta.setSummary(hdf.getValue("page.metaDescription",""));
- pageMeta.setLink(getPageUrlNormalized(filename));
+ pageMeta.setSummary(hdf.getValue("page.summary",""));
+ pageMeta.setLink(filename);
pageMeta.setGroup(getStringValueNormalized(hdf,"sample.group"));
pageMeta.setKeywords(getPageTagsNormalized(hdf, "page.tags"));
pageMeta.setTags(getPageTagsNormalized(hdf, "meta.tags"));
- pageMeta.setImage(getImageUrlNormalized(hdf.getValue("page.image", "")));
+ pageMeta.setImage(getStringValueNormalized(hdf, "page.image"));
pageMeta.setLang(getLangStringNormalized(filename));
pageMeta.setType(getStringValueNormalized(hdf, "page.type"));
appendMetaNodeByType(pageMeta, tagList);
}
- }
-
- /**
- * Attempt to infer page metadata based on the contents of the
- * file. Load and parse the file as a dom tree. Select values
- * in this order: 1. dom node specifically tagged with
- * microdata (itemprop). 2. first qualitifed p or img node.
- *
- * @param docfile The file from which to extract metadata.
- * @param hdf Data object in which to store the metadata values.
- * @param needsSummary Whether to extract summary metadata.
- * @param needsImage Whether to extract image metadata.
- */
- public static void inferMetadata(String docfile, Data hdf,
- Boolean needsSummary, Boolean needsImage) {
- String sum = "";
- String imageUrl = "";
- String sumFrom = needsSummary ? "none" : "hdf";
- String imgFrom = needsImage ? "none" : "hdf";
- String filedata = hdf.getValue("commentText", "");
- if (Doclava.META_DBG) System.out.println("----- " + docfile + "\n");
-
- try {
- XPathFactory xpathFac = XPathFactory.newInstance();
- XPath xpath = xpathFac.newXPath();
- InputStream inputStream = new ByteArrayInputStream(filedata.getBytes());
- XMLReader reader = new Parser();
- reader.setFeature(Parser.namespacesFeature, false);
- reader.setFeature(Parser.namespacePrefixesFeature, false);
- reader.setFeature(Parser.ignoreBogonsFeature, true);
-
- Transformer transformer = TransformerFactory.newInstance().newTransformer();
- DOMResult result = new DOMResult();
- transformer.transform(new SAXSource(reader, new InputSource(inputStream)), result);
- org.w3c.dom.Node htmlNode = result.getNode();
-
- if (needsSummary) {
- StringBuilder sumStrings = new StringBuilder();
- XPathExpression ItempropDescExpr = xpath.compile("/descendant-or-self::*"
- + "[@itemprop='description'][1]//text()[string(.)]");
- org.w3c.dom.NodeList nodes = (org.w3c.dom.NodeList) ItempropDescExpr.evaluate(htmlNode,
- XPathConstants.NODESET);
- if (nodes.getLength() > 0) {
- for (int i = 0; i < nodes.getLength(); i++) {
- String tx = nodes.item(i).getNodeValue();
- sumStrings.append(tx);
- sumFrom = "itemprop";
- }
- } else {
- XPathExpression FirstParaExpr = xpath.compile("//p[not(../../../"
- + "@class='notice-developers') and not(../@class='sidebox')"
- + "and not(@class)]//text()");
- nodes = (org.w3c.dom.NodeList) FirstParaExpr.evaluate(htmlNode, XPathConstants.NODESET);
- if (nodes.getLength() > 0) {
- for (int i = 0; i < nodes.getLength(); i++) {
- String tx = nodes.item(i).getNodeValue();
- sumStrings.append(tx + " ");
- sumFrom = "markup";
- }
- }
- }
- //found a summary string, now normalize it
- sum = sumStrings.toString().trim();
- if ((sum != null) && (!"".equals(sum))) {
- sum = getSummaryNormalized(sum);
- }
- //normalized summary ended up being too short to be meaningful
- if ("".equals(sum)) {
- if (Doclava.META_DBG) System.out.println("Warning: description too short! ("
- + sum.length() + "chars) ...\n\n");
- }
- //summary looks good, store it to the file hdf data
- hdf.setValue("page.metaDescription", sum);
- }
- if (needsImage) {
- XPathExpression ItempropImageExpr = xpath.compile("//*[@itemprop='image']/@src");
- org.w3c.dom.NodeList imgNodes = (org.w3c.dom.NodeList) ItempropImageExpr.evaluate(htmlNode,
- XPathConstants.NODESET);
- if (imgNodes.getLength() > 0) {
- imageUrl = imgNodes.item(0).getNodeValue();
- imgFrom = "itemprop";
- } else {
- XPathExpression FirstImgExpr = xpath.compile("//img/@src");
- imgNodes = (org.w3c.dom.NodeList) FirstImgExpr.evaluate(htmlNode, XPathConstants.NODESET);
- if (imgNodes.getLength() > 0) {
- //iterate nodes looking for valid image url and normalize.
- for (int i = 0; i < imgNodes.getLength(); i++) {
- String tx = imgNodes.item(i).getNodeValue();
- //qualify and normalize the image
- imageUrl = getImageUrlNormalized(tx);
- //this img src did not qualify, keep looking...
- if ("".equals(imageUrl)) {
- if (Doclava.META_DBG) System.out.println(" >>>>> Discarded image: " + tx);
- continue;
- } else {
- imgFrom = "markup";
- break;
- }
- }
- }
- }
- //img src url looks good, store it to the file hdf data
- hdf.setValue("page.image", imageUrl);
- }
- if (Doclava.META_DBG) System.out.println("Image (" + imgFrom + "): " + imageUrl);
- if (Doclava.META_DBG) System.out.println("Summary (" + sumFrom + "): " + sum.length()
- + " chars\n\n" + sum + "\n");
- return;
-
- } catch (Exception e) {
- if (Doclava.META_DBG) System.out.println(" >>>>> Exception: " + e + "\n");
- }
+ return tagList;
}
/**
@@ -273,38 +126,25 @@
*/
public static String getPageTagsNormalized(Data hdf, String tag) {
- String normTags = "";
StringBuilder tags = new StringBuilder();
String tagList = hdf.getValue(tag, "");
- if (tag.equals("meta.tags") && (tagList.equals(""))) {
- //use keywords as tags if no meta tags are available
- tagList = hdf.getValue("page.tags", "");
- }
if (!tagList.equals("")) {
tagList = tagList.replaceAll("\"", "");
String[] tagParts = tagList.split(",");
for (int iter = 0; iter < tagParts.length; iter++) {
- tags.append("\"");
+ tags.append("'");
if (tag.equals("meta.tags") && sLowercaseTags) {
tagParts[iter] = tagParts[iter].toLowerCase();
} else if (tag.equals("page.tags") && sLowercaseKeywords) {
tagParts[iter] = tagParts[iter].toLowerCase();
}
- if (tag.equals("meta.tags")) {
- //tags.append("#"); //to match hashtag format used with yt/blogger resources
- tagParts[iter] = tagParts[iter].replaceAll(" ","");
- }
tags.append(tagParts[iter].trim());
- tags.append("\"");
+ tags.append("'");
if (iter < tagParts.length - 1) {
tags.append(",");
}
}
}
- //write this back to hdf to expose through js
- if (tag.equals("meta.tags")) {
- hdf.setValue(tag, tags.toString());
- }
return tags.toString();
}
@@ -321,8 +161,8 @@
public static String getStringValueNormalized(Data hdf, String tag) {
StringBuilder outString = new StringBuilder();
String tagList = hdf.getValue(tag, "");
- tagList.replaceAll("\"", "");
if (!tagList.isEmpty()) {
+ tagList.replaceAll("\"", "");
int end = tagList.indexOf(",");
if (end != -1) {
tagList = tagList.substring(0,end);
@@ -348,7 +188,7 @@
StringBuilder outTitle = new StringBuilder();
String title = hdf.getValue(tag, "");
if (!title.isEmpty()) {
- title = escapeString(title);
+ title = title.replaceAll("\"", "'");
if (title.indexOf("<span") != -1) {
String[] splitTitle = title.split("<span(.*?)</span>");
title = splitTitle[0];
@@ -386,99 +226,6 @@
}
/**
- * Normalize a page summary string and truncate as needed. Strings
- * exceeding max_chars are truncated at the first word boundary
- * following the max_size marker. Strings smaller than min_chars
- * are discarded (as they are assumed to be too little context).
- *
- * @param s String extracted from the page as it's summary.
- * @return A normalized string value.
- */
- public static String getSummaryNormalized(String s) {
- String str = "";
- int max_chars = 250;
- int min_chars = 50;
- int marker = 0;
- if (s.length() < min_chars) {
- return str;
- } else {
- str = s.replaceAll("^\"|\"$", "");
- str = str.replaceAll("\\s+", " ");
- str = JD_TAG_PATTERN.matcher(str).replaceAll("$1");
- str = escapeString(str);
- BreakIterator bi = BreakIterator.getWordInstance();
- bi.setText(str);
- if (str.length() > max_chars) {
- marker = bi.following(max_chars);
- } else {
- marker = bi.last();
- }
- str = str.substring(0, marker);
- str = str.concat("\u2026" );
- }
- return str;
- }
-
- public static String escapeString(String s) {
- s = s.replaceAll("\"", """);
- s = s.replaceAll("\'", "'");
- s = s.replaceAll("<", "<");
- s = s.replaceAll(">", ">");
- s = s.replaceAll("/", "/");
- return s;
- }
-
- //Disqualify img src urls that include these substrings
- public static String[] IMAGE_EXCLUDE = {"/triangle-", "favicon","android-logo",
- "icon_play.png", "robot-tiny"};
-
- public static boolean inList(String s, String[] list) {
- for (String t : list) {
- if (s.contains(t)) {
- return true;
- }
- }
- return false;
- }
-
- /**
- * Normalize an img src url by removing docRoot and leading
- * slash for local image references. These are added later
- * in js to support offline mode and keep path reference
- * format consistent with hrefs.
- *
- * @param url Abs or rel url sourced from img src.
- * @return Normalized url if qualified, else empty
- */
- public static String getImageUrlNormalized(String url) {
- String absUrl = "";
- // validate to avoid choosing using specific images
- if ((url != null) && (!url.equals("")) && (!inList(url, IMAGE_EXCLUDE))) {
- absUrl = url.replace("{@docRoot}", "");
- absUrl = absUrl.replaceFirst("^/(?!/)", "");
- }
- return absUrl;
- }
-
- /**
- * Normalize an href url by removing docRoot and leading
- * slash for local image references. These are added later
- * in js to support offline mode and keep path reference
- * format consistent with hrefs.
- *
- * @param url Abs or rel page url sourced from href
- * @return Normalized url, either abs or rel to root
- */
- public static String getPageUrlNormalized(String url) {
- String absUrl = "";
- if ((url !=null) && (!url.equals(""))) {
- absUrl = url.replace("{@docRoot}", "");
- absUrl = absUrl.replaceFirst("^/(?!/)", "");
- }
- return absUrl;
- }
-
- /**
* Given a metadata node, add it as a child of a root node based on its
* type. If there is no root node that matches the node's type, create one
* and add the metadata node as a child node.
@@ -525,7 +272,6 @@
for (String t : nodeTags) { //process each of the meta.tags
for (Node n : rootTagNodesList) {
if (n.getLabel().equals(t.toString())) {
- n.getTags().add(String.valueOf(iter));
matched = true;
break; // add to the first root node only
} // tag did not match
@@ -637,16 +383,16 @@
final int n = list.size();
for (int i = 0; i < n; i++) {
buf.append("\n {\n");
- buf.append(" \"title\":\"" + list.get(i).mLabel + "\",\n" );
- buf.append(" \"titleFriendly\":\"" + list.get(i).mTitleFriendly + "\",\n" );
- buf.append(" \"summary\":\"" + list.get(i).mSummary + "\",\n" );
- buf.append(" \"url\":\"" + list.get(i).mLink + "\",\n" );
- buf.append(" \"group\":\"" + list.get(i).mGroup + "\",\n" );
+ buf.append(" title:\"" + list.get(i).mLabel + "\",\n" );
+ buf.append(" titleFriendly:\"" + list.get(i).mTitleFriendly + "\",\n" );
+ buf.append(" summary:\"" + list.get(i).mSummary + "\",\n" );
+ buf.append(" url:\"" + list.get(i).mLink + "\",\n" );
+ buf.append(" group:\"" + list.get(i).mGroup + "\",\n" );
list.get(i).renderArrayType(buf, list.get(i).mKeywords, "keywords");
list.get(i).renderArrayType(buf, list.get(i).mTags, "tags");
- buf.append(" \"image\":\"" + list.get(i).mImage + "\",\n" );
- buf.append(" \"lang\":\"" + list.get(i).mLang + "\",\n" );
- buf.append(" \"type\":\"" + list.get(i).mType + "\"");
+ buf.append(" image:\"" + list.get(i).mImage + "\",\n" );
+ buf.append(" lang:\"" + list.get(i).mLang + "\",\n" );
+ buf.append(" type:\"" + list.get(i).mType + "\"");
buf.append("\n }");
if (i != n - 1) {
buf.append(", ");
@@ -688,6 +434,7 @@
} else {
final int n = list.size();
for (int i = 0; i < n; i++) {
+
buf.append("\n " + list.get(i).mLabel + ":[");
renderArrayValue(buf, list.get(i).mTags);
buf.append("]");
@@ -705,7 +452,7 @@
* @param key The key for the pair.
*/
void renderArrayType(StringBuilder buf, List<String> type, String key) {
- buf.append(" \"" + key + "\": [");
+ buf.append(" " + key + ": [");
renderArrayValue(buf, type);
buf.append("],\n");
}
diff --git a/src/com/google/doclava/SampleCode.java b/src/com/google/doclava/SampleCode.java
index 57f1c54..45f9833 100644
--- a/src/com/google/doclava/SampleCode.java
+++ b/src/com/google/doclava/SampleCode.java
@@ -296,6 +296,8 @@
ClearPage.write(hdf, "sampleindex.cs", mDest + "index" + Doclava.htmlExtension);
} else {
DocFile.writePage(filename, rel, mDest + "index" + Doclava.htmlExtension, hdf);
+ PageMetadata.setPageMetadata(f, rel, mDest + "index" + Doclava.htmlExtension,
+ hdf, Doclava.sTaglist);
}
} else if (f.isFile()) {
//gather metadata for toc and jd_lists_unified
diff --git a/src/com/google/doclava/Scoped.java b/src/com/google/doclava/Scoped.java
index 03e42f9..931f299 100644
--- a/src/com/google/doclava/Scoped.java
+++ b/src/com/google/doclava/Scoped.java
@@ -24,6 +24,4 @@
boolean isPackagePrivate();
boolean isPrivate();
-
- boolean isHidden();
}
diff --git a/src/com/google/doclava/SinceTagger.java b/src/com/google/doclava/SinceTagger.java
index 858d98f..b8ad418 100644
--- a/src/com/google/doclava/SinceTagger.java
+++ b/src/com/google/doclava/SinceTagger.java
@@ -31,7 +31,7 @@
/**
* Applies version information to the Doclava class model from apicheck XML files. Sample usage:
- *
+ *
* <pre>
* ClassInfo[] classInfos = ...
*
@@ -59,7 +59,7 @@
for (Map.Entry<String, String> versionSpec : xmlToName.entrySet()) {
String xmlFile = versionSpec.getKey();
String versionName = versionSpec.getValue();
-
+
ApiInfo specApi;
try {
specApi = new ApiCheck().parseApi(xmlFile);
@@ -96,7 +96,7 @@
/**
* Applies the version information to {@code classDocs} where not already present.
- *
+ *
* @param versionName the version name
* @param specApi the spec for this version. If a symbol is in this spec, it was present in the
* named version
@@ -266,7 +266,8 @@
List<T> result = Collections.emptyList();
for (T t : all) {
// if this member has version info or isn't documented, skip it
- if (t.getSince() != null || t.isHidden() || !checkLevelRecursive(t.realContainingClass())) {
+ if (t.getSince() != null || t.isHiddenOrRemoved() ||
+ !checkLevelRecursive(t.realContainingClass())) {
continue;
}
diff --git a/src/com/google/doclava/Stubs.java b/src/com/google/doclava/Stubs.java
index 9b9fc6e..12a7df5 100644
--- a/src/com/google/doclava/Stubs.java
+++ b/src/com/google/doclava/Stubs.java
@@ -32,12 +32,14 @@
public class Stubs {
public static void writeStubsAndApi(String stubsDir, String apiFile, String keepListFile,
- HashSet<String> stubPackages) {
+ String removedApiFile, HashSet<String> stubPackages) {
// figure out which classes we need
final HashSet<ClassInfo> notStrippable = new HashSet<ClassInfo>();
ClassInfo[] all = Converter.allClasses();
PrintStream apiWriter = null;
PrintStream keepListWriter = null;
+ PrintStream removedApiWriter = null;
+
if (apiFile != null) {
try {
File xml = new File(apiFile);
@@ -58,6 +60,17 @@
"Cannot open file for write.");
}
}
+ if (removedApiFile != null) {
+ try {
+ File removedApi = new File(removedApiFile);
+ removedApi.getParentFile().mkdirs();
+ removedApiWriter = new PrintStream(
+ new BufferedOutputStream(new FileOutputStream(removedApi)));
+ } catch (FileNotFoundException e) {
+ Errors.error(Errors.IO_ERROR, new SourcePositionInfo(removedApiFile, 0, 0),
+ "Cannot open file for write");
+ }
+ }
// If a class is public or protected, not hidden, and marked as included,
// then we can't strip it
for (ClassInfo cl : all) {
@@ -69,10 +82,10 @@
// complain about anything that looks includeable but is not supposed to
// be written, e.g. hidden things
for (ClassInfo cl : notStrippable) {
- if (!cl.isHidden()) {
+ if (!cl.isHiddenOrRemoved()) {
for (MethodInfo m : cl.selfMethods()) {
- if (m.isHidden()) {
- Errors.error(Errors.UNAVAILABLE_SYMBOL, m.position(), "Reference to hidden method "
+ if (m.isHiddenOrRemoved()) {
+ Errors.error(Errors.UNAVAILABLE_SYMBOL, m.position(), "Reference to unavailable method "
+ m.name());
} else if (m.isDeprecated()) {
// don't bother reporting deprecated methods
@@ -82,7 +95,7 @@
}
ClassInfo returnClass = m.returnType().asClassInfo();
- if (returnClass != null && returnClass.isHidden()) {
+ if (returnClass != null && returnClass.isHiddenOrRemoved()) {
Errors.error(Errors.UNAVAILABLE_SYMBOL, m.position(), "Method " + cl.qualifiedName()
+ "." + m.name() + " returns unavailable type " + returnClass.name());
}
@@ -90,8 +103,8 @@
for (ParameterInfo p : m.parameters()) {
TypeInfo t = p.type();
if (!t.isPrimitive()) {
- if (t.asClassInfo().isHidden()) {
- Errors.error(Errors.UNAVAILABLE_SYMBOL, m.position(), "Parameter of hidden type "
+ if (t.asClassInfo().isHiddenOrRemoved()) {
+ Errors.error(Errors.UNAVAILABLE_SYMBOL, m.position(), "Parameter of unavailable type "
+ t.fullName() + " in " + cl.qualifiedName() + "." + m.name() + "()");
}
}
@@ -100,13 +113,13 @@
// annotations are handled like methods
for (MethodInfo m : cl.annotationElements()) {
- if (m.isHidden()) {
- Errors.error(Errors.UNAVAILABLE_SYMBOL, m.position(), "Reference to hidden annotation "
+ if (m.isHiddenOrRemoved()) {
+ Errors.error(Errors.UNAVAILABLE_SYMBOL, m.position(), "Reference to unavailable annotation "
+ m.name());
}
ClassInfo returnClass = m.returnType().asClassInfo();
- if (returnClass != null && returnClass.isHidden()) {
+ if (returnClass != null && returnClass.isHiddenOrRemoved()) {
Errors.error(Errors.UNAVAILABLE_SYMBOL, m.position(), "Annotation '" + m.name()
+ "' returns unavailable type " + returnClass.name());
}
@@ -114,7 +127,7 @@
for (ParameterInfo p : m.parameters()) {
TypeInfo t = p.type();
if (!t.isPrimitive()) {
- if (t.asClassInfo().isHidden()) {
+ if (t.asClassInfo().isHiddenOrRemoved()) {
Errors.error(Errors.UNAVAILABLE_SYMBOL, p.position(),
"Reference to unavailable annotation class " + t.fullName());
}
@@ -128,6 +141,7 @@
}
}
+ // packages contains all the notStrippable classes mapped by their containing packages
HashMap<PackageInfo, List<ClassInfo>> packages = new HashMap<PackageInfo, List<ClassInfo>>();
for (ClassInfo cl : notStrippable) {
if (!cl.isDocOnly()) {
@@ -149,7 +163,6 @@
}
}
}
-
// write out the Api
if (apiWriter != null) {
writeApi(apiWriter, packages, notStrippable);
@@ -161,6 +174,23 @@
writeKeepList(keepListWriter, packages, notStrippable);
keepListWriter.close();
}
+
+ HashMap<PackageInfo, List<ClassInfo>> allPackageClassMap =
+ new HashMap<PackageInfo, List<ClassInfo>>();
+ for (ClassInfo cl : Converter.allClasses()) {
+ if (allPackageClassMap.containsKey(cl.containingPackage())) {
+ allPackageClassMap.get(cl.containingPackage()).add(cl);
+ } else {
+ ArrayList<ClassInfo> classes = new ArrayList<ClassInfo>();
+ classes.add(cl);
+ allPackageClassMap.put(cl.containingPackage(), classes);
+ }
+ }
+ // write out the removed Api
+ if (removedApiWriter != null) {
+ writeRemovedApi(removedApiWriter, allPackageClassMap, notStrippable);
+ removedApiWriter.close();
+ }
}
public static void cantStripThis(ClassInfo cl, HashSet<ClassInfo> notStrippable, String why) {
@@ -217,7 +247,7 @@
// blow open super class and interfaces
ClassInfo supr = cl.realSuperclass();
if (supr != null) {
- if (supr.isHidden()) {
+ if (supr.isHiddenOrRemoved()) {
// cl is a public class declared as extending a hidden superclass.
// this is not a desired practice but it's happened, so we deal
// with it by finding the first super class which passes checklevel for purposes of
@@ -256,7 +286,7 @@
for (TypeInfo tInfoType : pInfo.type().typeArguments()) {
if (tInfoType.asClassInfo() != null) {
ClassInfo tcl = tInfoType.asClassInfo();
- if (tcl.isHidden()) {
+ if (tcl.isHiddenOrRemoved()) {
Errors
.error(Errors.UNAVAILABLE_SYMBOL, mInfo.position(),
"Parameter of hidden type " + tInfoType.fullName() + " in "
@@ -445,8 +475,8 @@
// and the super class doesn't have a default constructor, write in a private constructor
// that works. TODO -- we generate this as protected, but we really should generate
// it as private unless it also exists in the real code.
- if ((cl.constructors().isEmpty() && (!cl.getNonWrittenConstructors().isEmpty() || fieldNeedsInitialization))
- && !cl.isAnnotation() && !cl.isInterface() && !cl.isEnum()) {
+ if ((cl.constructors().isEmpty() && (!cl.getNonWrittenConstructors().isEmpty() ||
+ fieldNeedsInitialization)) && !cl.isAnnotation() && !cl.isInterface() && !cl.isEnum()) {
// Errors.error(Errors.HIDDEN_CONSTRUCTOR,
// cl.position(), "No constructors " +
// "found and superclass has no parameterless constructor. A constructor " +
@@ -458,8 +488,9 @@
for (MethodInfo method : cl.allSelfMethods()) {
if (cl.isEnum()) {
- if (("values".equals(method.name()) && "()".equals(method.signature()))
- || ("valueOf".equals(method.name()) && "(java.lang.String)".equals(method.signature()))) {
+ if (("values".equals(method.name()) && "()".equals(method.signature())) ||
+ ("valueOf".equals(method.name()) &&
+ "(java.lang.String)".equals(method.signature()))) {
// skip these two methods on enums, because they're synthetic,
// although for some reason javadoc doesn't mark them as synthetic,
// maybe because they still want them documented
@@ -470,15 +501,18 @@
writeMethod(stream, method, false);
}
}
- // Write all methods that are hidden, but override abstract methods or interface methods.
+ // Write all methods that are hidden or removed, but override abstract methods or interface methods.
// These can't be hidden.
- for (MethodInfo method : cl.getHiddenMethods()) {
+ List<MethodInfo> hiddenAndRemovedMethods = cl.getHiddenMethods();
+ hiddenAndRemovedMethods.addAll(cl.getRemovedMethods());
+ for (MethodInfo method : hiddenAndRemovedMethods) {
MethodInfo overriddenMethod =
method.findRealOverriddenMethod(method.name(), method.signature(), notStrippable);
ClassInfo classContainingMethod =
method.findRealOverriddenClass(method.name(), method.signature());
- if (overriddenMethod != null && !overriddenMethod.isHidden() && !overriddenMethod.isDocOnly()
- && (overriddenMethod.isAbstract() || overriddenMethod.containingClass().isInterface())) {
+ if (overriddenMethod != null && !overriddenMethod.isHiddenOrRemoved() &&
+ !overriddenMethod.isDocOnly() &&
+ (overriddenMethod.isAbstract() || overriddenMethod.containingClass().isInterface())) {
method.setReason("1:" + classContainingMethod.qualifiedName());
cl.addMethod(method);
writeMethod(stream, method, false);
@@ -628,9 +662,9 @@
// Look only for overrides of an ancestor class implementation,
// not of e.g. an abstract or interface method declaration
if (!om.isAbstract()) {
- // If the parent is hidden, we can't rely on it to provide
+ // If the parent is hidden or removed, we can't rely on it to provide
// the API
- if (!om.isHidden()) {
+ if (!om.isHiddenOrRemoved()) {
// If the only "override" turns out to be in our own class
// (which sometimes happens in concrete subclasses of
// abstract base classes), it's not really an override
@@ -751,7 +785,7 @@
if (ann.type() != null && ann.type().qualifiedName().equals("java.lang.Override")) {
continue;
}
- if (!ann.type().isHidden()) {
+ if (!ann.type().isHiddenOrRemoved()) {
stream.println(ann.toString());
if (isDeprecated && ann.type() != null
&& ann.type().qualifiedName().equals("java.lang.Deprecated")) {
@@ -993,6 +1027,105 @@
return returnString;
}
+ static void writeRemovedApi(PrintStream apiWriter, HashMap<PackageInfo,
+ List<ClassInfo>> allPackageClassMap, Set<ClassInfo> notStrippable) {
+ final PackageInfo[] packages = allPackageClassMap.keySet().toArray(new PackageInfo[0]);
+ Arrays.sort(packages, PackageInfo.comparator);
+ for (PackageInfo pkg : packages) {
+ // beware that pkg.allClasses() has no class in it at the moment
+ final List<ClassInfo> classes = allPackageClassMap.get(pkg);
+ Collections.sort(classes, ClassInfo.comparator);
+ boolean hasWrittenPackageHead = false;
+ for (ClassInfo cl : classes) {
+ if (cl.hasRemovedSelfMembers()) {
+ if (!hasWrittenPackageHead) {
+ hasWrittenPackageHead = true;
+ apiWriter.print("package ");
+ apiWriter.print(pkg.qualifiedName());
+ apiWriter.print(" {\n\n");
+ }
+ writeClassRemovedSelfMembers(apiWriter, cl, notStrippable);
+ }
+ }
+
+ // the package contains some classes with some removed members
+ if (hasWrittenPackageHead) {
+ apiWriter.print("}\n\n");
+ }
+ }
+ }
+
+ /**
+ * Write the removed members of the class to removed.txt
+ */
+ private static void writeClassRemovedSelfMembers(PrintStream apiWriter, ClassInfo cl,
+ Set<ClassInfo> notStrippable) {
+ apiWriter.print(" ");
+ apiWriter.print(cl.scope());
+ if (cl.isStatic()) {
+ apiWriter.print(" static");
+ }
+ if (cl.isFinal()) {
+ apiWriter.print(" final");
+ }
+ if (cl.isAbstract()) {
+ apiWriter.print(" abstract");
+ }
+ if (cl.isDeprecated()) {
+ apiWriter.print(" deprecated");
+ }
+ apiWriter.print(" ");
+ apiWriter.print(cl.isInterface() ? "interface" : "class");
+ apiWriter.print(" ");
+ apiWriter.print(cl.name());
+
+ if (!cl.isInterface()
+ && !"java.lang.Object".equals(cl.qualifiedName())
+ && cl.realSuperclass() != null
+ && !"java.lang.Object".equals(cl.realSuperclass().qualifiedName())) {
+ apiWriter.print(" extends ");
+ apiWriter.print(cl.realSuperclass().qualifiedName());
+ }
+
+ ArrayList<ClassInfo> interfaces = cl.realInterfaces();
+ Collections.sort(interfaces, ClassInfo.comparator);
+ boolean first = true;
+ for (ClassInfo iface : interfaces) {
+ if (notStrippable.contains(iface)) {
+ if (first) {
+ apiWriter.print(" implements");
+ first = false;
+ }
+ apiWriter.print(" ");
+ apiWriter.print(iface.qualifiedName());
+ }
+ }
+
+ apiWriter.print(" {\n");
+
+ List<MethodInfo> constructors = cl.getRemovedConstructors();
+ for (MethodInfo mi : constructors) {
+ writeConstructorApi(apiWriter, mi);
+ }
+
+ List<MethodInfo> methods = cl.getRemovedSelfMethods();
+ for (MethodInfo mi : methods) {
+ writeMethodApi(apiWriter, mi);
+ }
+
+ List<FieldInfo> enums = cl.getRemovedSelfEnumConstants();
+ for (FieldInfo fi : enums) {
+ writeFieldApi(apiWriter, fi, "enum_constant");
+ }
+
+ List<FieldInfo> fields = cl.getRemovedSelfFields();
+ for (FieldInfo fi : fields) {
+ writeFieldApi(apiWriter, fi, "field");
+ }
+
+ apiWriter.print(" }\n\n");
+ }
+
public static void writeApi(PrintStream apiWriter, Collection<PackageInfo> pkgs) {
final PackageInfo[] packages = pkgs.toArray(new PackageInfo[pkgs.size()]);
Arrays.sort(packages, PackageInfo.comparator);
@@ -1163,7 +1296,8 @@
apiWriter.print(";\n");
}
- static void writeParametersApi(PrintStream apiWriter, MethodInfo method, ArrayList<ParameterInfo> params) {
+ static void writeParametersApi(PrintStream apiWriter, MethodInfo method,
+ ArrayList<ParameterInfo> params) {
apiWriter.print("(");
for (ParameterInfo pi : params) {
@@ -1297,9 +1431,8 @@
ArrayList<MethodInfo> methods = cl.allSelfMethods();
Collections.sort(methods, MethodInfo.comparator);
for (MethodInfo mi : methods) {
- if (!methodIsOverride(notStrippable, mi)) {
- writeMethodKeepList(keepListWriter, mi);
- }
+ // allSelfMethods is the non-hidden and visible methods. See Doclava.checkLevel.
+ writeMethodKeepList(keepListWriter, mi);
}
keepListWriter.print("\n");
diff --git a/src/com/google/doclava/TodoFile.java b/src/com/google/doclava/TodoFile.java
index 5cf4f1e..36df2c7 100644
--- a/src/com/google/doclava/TodoFile.java
+++ b/src/com/google/doclava/TodoFile.java
@@ -74,7 +74,7 @@
int classIndex = 0;
for (ClassInfo cl : classes) {
- if (cl.isHidden()) {
+ if (cl.isHiddenOrRemoved()){
continue;
}
diff --git a/src/com/google/doclava/apicheck/ApiCheck.java b/src/com/google/doclava/apicheck/ApiCheck.java
index fb5b011..28d7ce0 100644
--- a/src/com/google/doclava/apicheck/ApiCheck.java
+++ b/src/com/google/doclava/apicheck/ApiCheck.java
@@ -103,10 +103,16 @@
ApiInfo oldApi;
ApiInfo newApi;
-
+ ApiInfo oldRemovedApi;
+ ApiInfo newRemovedApi;
+
+ // commandline options look like:
+ // [other optoins] old_api.txt new_api.txt old_removed_api.txt new_removed_api.txt
try {
oldApi = parseApi(args.get(0));
newApi = parseApi(args.get(1));
+ oldRemovedApi = parseApi(args.get(2));
+ newRemovedApi = parseApi(args.get(3));
} catch (ApiParseException e) {
e.printStackTrace();
System.err.println("Error parsing API");
@@ -118,6 +124,10 @@
oldApi.isConsistent(newApi);
}
+ if (!Errors.hadError) {
+ oldRemovedApi.isConsistent(newRemovedApi);
+ }
+
return new Report(Errors.hadError ? 1 : 0, Errors.getErrors());
}