tequilaOS/platform_build
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Adding version information to DroidDoc. Rather than pulling the version from

Browse source 
@since tags in the code, it's pulled from the API XML files also used by
apicheck.

The code now reads the apicheck XML, and applies it's versions to the DroidDoc
class models. The models output the version to HDF, and that's picked up by
the CS templates.

The clearsilver templates will be changed to be pretty in a follow up change.
This commit is contained in:
Jesse Wilson 2009-06-01 17:59:44 -07:00
parent 3c3fae144e
commit 5e0dd414ff
17 changed files with 316 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

107
tools/apicheck/src/com/android/apicheck/ApiCheck.java
View file

@ -20,7 +20,6 @@ import org.xml.sax.*;
import org.xml.sax.helpers.*;
import java.io.*;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Stack;
public class ApiCheck {
@ -83,62 +82,62 @@ public class ApiCheck {
}
}
String xmlFileName = args.get(0);
String xmlFileNameNew = args.get(1);
XMLReader xmlreader = null;
try {
// parse the XML files into our data structures
xmlreader = XMLReaderFactory.createXMLReader();
ApiCheck acheck = new ApiCheck();
MakeHandler handler = acheck.new MakeHandler();
xmlreader.setContentHandler(handler);
xmlreader.setErrorHandler(handler);
FileReader filereader = new FileReader(xmlFileName);
xmlreader.parse(new InputSource(filereader));
FileReader filereaderNew = new FileReader(xmlFileNameNew);
xmlreader.parse(new InputSource(filereaderNew));
ApiCheck acheck = new ApiCheck();
// establish the superclass relationships
handler.getOldApi().resolveSuperclasses();
handler.getNewApi().resolveSuperclasses();
// finally, run the consistency check
handler.getOldApi().isConsistent(handler.getNewApi());
ApiInfo oldApi = acheck.parseApi(args.get(0));
ApiInfo newApi = acheck.parseApi(args.get(1));
} catch (SAXParseException e) {
Errors.error(Errors.PARSE_ERROR,
new SourcePositionInfo(xmlFileName, e.getLineNumber(), 0),
e.getMessage());
} catch (Exception e) {
e.printStackTrace();
Errors.error(Errors.PARSE_ERROR,
new SourcePositionInfo(xmlFileName, 0, 0),
e.getMessage());
}
// only run the consistency check if we haven't had XML parse errors
if (!Errors.hadError) {
oldApi.isConsistent(newApi);
}
Errors.printErrors();
System.exit(Errors.hadError ? 1 : 0);
}
private class MakeHandler extends DefaultHandler {
public ApiInfo parseApi(String xmlFile) {
FileReader fileReader = null;
try {
XMLReader xmlreader = XMLReaderFactory.createXMLReader();
MakeHandler handler = new MakeHandler();
xmlreader.setContentHandler(handler);
xmlreader.setErrorHandler(handler);
fileReader = new FileReader(xmlFile);
xmlreader.parse(new InputSource(fileReader));
ApiInfo apiInfo = handler.getApi();
apiInfo.resolveSuperclasses();
return apiInfo;
} catch (SAXParseException e) {
Errors.error(Errors.PARSE_ERROR,
new SourcePositionInfo(xmlFile, e.getLineNumber(), 0),
e.getMessage());
} catch (Exception e) {
e.printStackTrace();
Errors.error(Errors.PARSE_ERROR,
new SourcePositionInfo(xmlFile, 0, 0), e.getMessage());
} finally {
if (fileReader != null) {
try {
fileReader.close();
} catch (IOException ignored) {}
}
}
return null;
}
private static class MakeHandler extends DefaultHandler {
private Integer mWarningCount;
private ApiInfo mOriginalApi;
private ApiInfo mNewApi;
private boolean mOldApi;
private ApiInfo mApi;
private PackageInfo mCurrentPackage;
private ClassInfo mCurrentClass;
private AbstractMethodInfo mCurrentMethod;
private ConstructorInfo mCurrentConstructor;
private Stack<ClassInfo> mClassScope = new Stack<ClassInfo>();
public MakeHandler() {
super();
mOriginalApi = new ApiInfo();
mNewApi = new ApiInfo();
mOldApi = true;
mApi = new ApiInfo();
}
public void startElement(String uri, String localName, String qName,
@ -229,25 +228,11 @@ public class ApiCheck {
mCurrentPackage.addClass(mCurrentClass);
mCurrentClass = mClassScope.pop();
} else if (qName.equals("package")){
if (mOldApi) {
mOriginalApi.addPackage(mCurrentPackage);
} else {
mNewApi.addPackage(mCurrentPackage);
}
mApi.addPackage(mCurrentPackage);
}
}
public void endDocument() {
mOldApi = !mOldApi;
}
public ApiInfo getOldApi() {
return mOriginalApi;
}
public ApiInfo getNewApi() {
return mNewApi;
}
public ApiInfo getApi() {
return mApi;
}
}
}

28
tools/apicheck/src/com/android/apicheck/ClassInfo.java
View file

@ -187,8 +187,8 @@ public class ClassInfo {
}
for (FieldInfo mInfo : mFields.values()) {
if (cl.mFields.containsKey(mInfo.qualifiedName())) {
if (!mInfo.isConsistent(cl.mFields.get(mInfo.qualifiedName()))) {
if (cl.mFields.containsKey(mInfo.name())) {
if (!mInfo.isConsistent(cl.mFields.get(mInfo.name()))) {
consistent = false;
}
} else {
@ -267,7 +267,7 @@ public class ClassInfo {
}
public void addField(FieldInfo fInfo) {
mFields.put(fInfo.qualifiedName(), fInfo);
mFields.put(fInfo.name(), fInfo);
}
@ -279,4 +279,26 @@ public class ClassInfo {
return mExistsInBoth;
}
public Map<String, ConstructorInfo> allConstructors() {
return mConstructors;
}
public Map<String, FieldInfo> allFields() {
return mFields;
}
public Map<String, MethodInfo> allMethods() {
return mMethods;
}
/**
* Returns the class hierarchy for this class, starting with this class.
*/
public Iterable<ClassInfo> hierarchy() {
List<ClassInfo> result = new ArrayList<ClassInfo>(4);
for (ClassInfo c = this; c != null; c = c.mSuperClass) {
result.add(c);
}
return result;
}
}

7
tools/apicheck/src/com/android/apicheck/ConstructorInfo.java
View file

@ -55,11 +55,12 @@ public class ConstructorInfo implements AbstractMethodInfo {
}
public String getHashableName() {
String returnString = qualifiedName();
StringBuilder result = new StringBuilder();
result.append(name());
for (ParameterInfo pInfo : mParameters) {
returnString += ":" + pInfo.getType();
result.append(":").append(pInfo.getType());
}
return returnString;
return result.toString();
}
public boolean isInBoth() {

2
tools/apicheck/src/com/android/apicheck/MethodInfo.java
View file

@ -195,7 +195,7 @@ public class MethodInfo implements AbstractMethodInfo {
}
public String getHashableName() {
return qualifiedName() + getParameterHash();
return name() + getParameterHash();
}
public String getSignature() {

2
tools/droiddoc/src/Android.mk
View file

@ -47,6 +47,7 @@ LOCAL_SRC_FILES := \
SampleTagInfo.java \
Scoped.java \
SeeTagInfo.java \
SinceTagger.java \
Sorter.java \
SourcePositionInfo.java \
Stubs.java \
@ -57,6 +58,7 @@ LOCAL_SRC_FILES := \
TypeInfo.java
LOCAL_JAVA_LIBRARIES := \
apicheck \
clearsilver
LOCAL_CLASSPATH := \

1
tools/droiddoc/src/ClassInfo.java
View file

@ -907,6 +907,7 @@ public class ClassInfo extends DocInfo implements ContainerInfo, Comparable, Sco
if (kind != null) {
data.setValue("class.kind", kind);
}
data.setValue("class.since", getSince());
// the containing package -- note that this can be passed to type_link,
// but it also contains the list of all of the packages

9
tools/droiddoc/src/DocInfo.java
View file

@ -51,8 +51,17 @@ public abstract class DocInfo
public abstract ContainerInfo parent();
public void setSince(String since) {
mSince = since;
}
public String getSince() {
return mSince;
}
private String mRawCommentText;
Comment mComment;
SourcePositionInfo mPosition;
private String mSince;
}

15
tools/droiddoc/src/DroidDoc.java
View file

@ -98,6 +98,7 @@ public class DroidDoc
String apiFile = null;
String debugStubsFile = "";
HashSet<String> stubPackages = null;
SinceTagger sinceTagger = new SinceTagger();
root = r;
@ -190,6 +191,9 @@ public class DroidDoc
else if (a[0].equals("-nodocs")) {
noDocs = true;
}
else if (a[0].equals("-since")) {
sinceTagger.addVersion(a[1], a[2]);
}
}
// read some prefs from the template
@ -203,6 +207,9 @@ public class DroidDoc
if (!noDocs) {
long startTime = System.nanoTime();
// Apply @since tags from the XML file
sinceTagger.tagAll(Converter.rootClasses());
// Files for proofreading
if (proofreadFile != null) {
Proofread.initProofread(proofreadFile);
@ -260,7 +267,7 @@ public class DroidDoc
if (stubsDir != null) {
Stubs.writeStubs(stubsDir, apiXML, apiFile, stubPackages);
}
Errors.printErrors();
return !Errors.hadError;
}
@ -409,9 +416,12 @@ public class DroidDoc
if (option.equals("-nodocs")) {
return 1;
}
if (option.equals("-since")) {
return 3;
}
return 0;
}
public static boolean validOptions(String[][] options, DocErrorReporter r)
{
for (String[] a: options) {
@ -777,6 +787,7 @@ public class DroidDoc
String name = pkg.name();
data.setValue("package.name", name);
data.setValue("package.since", pkg.getSince());
data.setValue("package.descr", "...description...");
makeClassListHDF(data, "package.interfaces",

2
tools/droiddoc/src/Errors.java
View file

@ -114,6 +114,7 @@ public class Errors
public static Error DEPRECATION_MISMATCH = new Error(13, WARNING);
public static Error MISSING_COMMENT = new Error(14, WARNING);
public static Error IO_ERROR = new Error(15, HIDDEN);
public static Error NO_SINCE_DATA = new Error(16, WARNING);
public static Error[] ERRORS = {
UNRESOLVED_LINK,
@ -129,6 +130,7 @@ public class Errors
HIDDEN_SUPERCLASS,
DEPRECATED,
IO_ERROR,
NO_SINCE_DATA,
};
public static boolean setErrorLevel(int code, int level) {

1
tools/droiddoc/src/FieldInfo.java
View file

@ -223,6 +223,7 @@ public class FieldInfo extends MemberInfo
TagInfo.makeHDF(data, base + ".descr", inlineTags());
TagInfo.makeHDF(data, base + ".deprecated", comment().deprecatedTags());
TagInfo.makeHDF(data, base + ".seeAlso", comment().seeTags());
data.setValue(base + ".since", getSince());
data.setValue(base + ".final", isFinal() ? "final" : "");
data.setValue(base + ".static", isStatic() ? "static" : "");
if (isPublic()) {

17
tools/droiddoc/src/MethodInfo.java
View file

@ -15,9 +15,8 @@
*/
import org.clearsilver.HDF;
import org.clearsilver.CS;
import java.util.*;
import java.io.*;
public class MethodInfo extends MemberInfo
{
@ -357,6 +356,19 @@ public class MethodInfo extends MemberInfo
return s;
}
/**
* Returns a name consistent with the {@link
* com.android.apicheck.MethodInfo#getHashableName()}.
*/
public String getHashableName() {
StringBuilder result = new StringBuilder();
result.append(name());
for (ParameterInfo pInfo : mParameters) {
result.append(":").append(pInfo.type().fullName());
}
return result.toString();
}
private boolean inList(ClassInfo item, ThrowsTagInfo[] list)
{
int len = list.length;
@ -545,6 +557,7 @@ public class MethodInfo extends MemberInfo
TagInfo.makeHDF(data, base + ".descr", inlineTags());
TagInfo.makeHDF(data, base + ".deprecated", deprecatedTags());
TagInfo.makeHDF(data, base + ".seeAlso", seeTags());
data.setValue(base + ".since", getSince());
ParamTagInfo.makeHDF(data, base + ".paramTags", paramTags());
AttrTagInfo.makeReferenceHDF(data, base + ".attrRefs", comment().attrTags());
ThrowsTagInfo.makeHDF(data, base + ".throws", throwsTags());

182
tools/droiddoc/src/SinceTagger.java Normal file
View file

@ -0,0 +1,182 @@
// Copyright 2009 Google Inc. All Rights Reserved.
import com.android.apicheck.*;
import java.util.*;
/**
* Applies version information to the DroidDoc class model from apicheck XML
* files. Sample usage:
* <pre>
* ClassInfo[] classInfos = ...
*
* SinceTagger sinceTagger = new SinceTagger()
* sinceTagger.addVersion("frameworks/base/api/1.xml", "Android 1.0")
* sinceTagger.addVersion("frameworks/base/api/2.xml", "Android 1.5")
* sinceTagger.tagAll(...);
* </pre>
*/
public class SinceTagger {
private final Map<String, String> xmlToName
= new LinkedHashMap<String, String>();
/**
* Specifies the apicheck XML file and the API version it holds. Calls to
* this method should be called in order from oldest version to newest.
*/
public void addVersion(String file, String name) {
xmlToName.put(file, name);
}
public void tagAll(ClassInfo[] classDocs) {
// read through the XML files in order, applying their since information
// to the Javadoc models
for (Map.Entry<String, String> versionSpec : xmlToName.entrySet()) {
String xmlFile = versionSpec.getKey();
String versionName = versionSpec.getValue();
ApiInfo specApi = new ApiCheck().parseApi(xmlFile);
applyVersionsFromSpec(versionName, specApi, classDocs);
}
if (!xmlToName.isEmpty()) {
warnForMissingVersions(classDocs);
}
}
/**
* 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
* @param classDocs the doc model to update
*/
private void applyVersionsFromSpec(String versionName,
ApiInfo specApi, ClassInfo[] classDocs) {
for (ClassInfo classDoc : classDocs) {
com.android.apicheck.PackageInfo packageSpec
= specApi.getPackages().get(classDoc.containingPackage().name());
if (packageSpec == null) {
continue;
}
com.android.apicheck.ClassInfo classSpec
= packageSpec.allClasses().get(classDoc.name());
if (classSpec == null) {
continue;
}
versionPackage(versionName, classDoc.containingPackage());
versionClass(versionName, classDoc);
versionConstructors(versionName, classSpec, classDoc);
versionFields(versionName, classSpec, classDoc);
versionMethods(versionName, classSpec, classDoc);
}
}
/**
* Applies version information to {@code doc} where not already present.
*/
private void versionPackage(String versionName, PackageInfo doc) {
if (doc.getSince() == null) {
doc.setSince(versionName);
}
}
/**
* Applies version information to {@code doc} where not already present.
*/
private void versionClass(String versionName, ClassInfo doc) {
if (doc.getSince() == null) {
doc.setSince(versionName);
}
}
/**
* Applies version information from {@code spec} to {@code doc} where not
* already present.
*/
private void versionConstructors(String versionName,
com.android.apicheck.ClassInfo spec, ClassInfo doc) {
for (MethodInfo constructor : doc.constructors()) {
if (constructor.getSince() == null
&& spec.allConstructors().containsKey(constructor.getHashableName())) {
constructor.setSince(versionName);
}
}
}
/**
* Applies version information from {@code spec} to {@code doc} where not
* already present.
*/
private void versionFields(String versionName,
com.android.apicheck.ClassInfo spec, ClassInfo doc) {
for (FieldInfo field : doc.fields()) {
if (field.getSince() == null
&& spec.allFields().containsKey(field.name())) {
field.setSince(versionName);
}
}
}
/**
* Applies version information from {@code spec} to {@code doc} where not
* already present.
*/
private void versionMethods(String versionName,
com.android.apicheck.ClassInfo spec, ClassInfo doc) {
for (MethodInfo method : doc.methods()) {
if (method.getSince() != null) {
continue;
}
for (com.android.apicheck.ClassInfo superclass : spec.hierarchy()) {
if (superclass.allMethods().containsKey(method.getHashableName())) {
method.setSince(versionName);
break;
}
}
}
}
/**
* Warns if any symbols are missing version information. When configured
* properly, this will yield zero warnings because {@code apicheck}
* guarantees that all symbols are present in the most recent API.
*/
private void warnForMissingVersions(ClassInfo[] classDocs) {
for (ClassInfo claz : classDocs) {
if (claz.getSince() == null) {
Errors.error(Errors.NO_SINCE_DATA, claz.position(),
"XML missing class " + claz.qualifiedName());
}
for (FieldInfo field : claz.fields()) {
if (field.getSince() == null) {
Errors.error(Errors.NO_SINCE_DATA, field.position(),
"XML missing field "
+ claz.qualifiedName() + "#" + field .name());
}
}
for (MethodInfo constructor : claz.constructors()) {
if (constructor.getSince() == null) {
Errors.error(Errors.NO_SINCE_DATA, constructor.position(),
"XML missing constructor "
+ claz.qualifiedName() + "#" + constructor.getHashableName());
}
}
for (MethodInfo method : claz.methods()) {
if (method.getSince() == null) {
Errors.error(Errors.NO_SINCE_DATA, method.position(),
"XML missing method "
+ claz.qualifiedName() + "#" + method .getHashableName());
}
}
}
}
}

1
tools/droiddoc/templates/class.cs
View file

@ -180,6 +180,7 @@ Summary:
<?cs /if ?>
<?cs call:see_also_tags(class.seeAlso) ?>
<?cs call:since_tags(class) ?>
</div><!-- jd-descr -->

9
tools/droiddoc/templates/macros.cs
View file

@ -115,9 +115,15 @@ def:see_also_tags(also) ?><?cs
/if ?>
<?cs /def ?>
<?cs # print the Since: section ?><?cs
def:since_tags(obj) ?>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Since <?cs var:obj.since ?></h5>
</div>
<?cs /def ?>
<?cs # Print the long-form description for something.
Uses the following fields: deprecated descr seeAlso ?><?cs
Uses the following fields: deprecated descr seeAlso since ?><?cs
def:description(obj) ?><?cs
call:deprecated_warning(obj) ?>
<div class="jd-tagdata jd-tagdescr"><p><?cs call:tag_list(obj.descr) ?></p></div><?cs
@ -165,6 +171,7 @@ def:description(obj) ?><?cs
</div><?cs
/if ?><?cs
call:see_also_tags(obj.seeAlso) ?><?cs
call:since_tags(obj) ?><?cs
/def ?>
<?cs # A table of links to classes with descriptions, as in a package file or the nested classes ?><?cs

1
tools/droiddoc/templates/package-descr.cs
View file

@ -21,6 +21,7 @@
<div class="jd-descr">
<p><?cs call:tag_list(package.descr) ?></p>
</div>
<?cs call:since_tags(package) ?>
<?cs include:"footer.cs" ?>
</div><!-- end jd-content -->

7
tools/droiddoc/test/stubs/func.sh
View file

@ -26,21 +26,22 @@ function build_stubs()
STUBS_DIR=$3
OBJ_DIR=out/stubs/$ID
PLATFORM=${HOST_OS}-${HOST_ARCH}
rm -rf $OBJ_DIR &> /dev/null
mkdir -p $OBJ_DIR
find $SRC_DIR -name '*.java' > $OBJ_DIR/javadoc-src-list
( \
LD_LIBRARY_PATH=out/host/darwin-x86/lib \
LD_LIBRARY_PATH=out/host/$PLATFORM/lib \
javadoc \
\@$OBJ_DIR/javadoc-src-list \
-J-Xmx512m \
-J-Djava.library.path=out/host/darwin-x86/lib \
-J-Djava.library.path=out/host/$PLATFORM/lib \
\
-quiet \
-doclet DroidDoc \
-docletpath out/host/darwin-x86/framework/clearsilver.jar:out/host/darwin-x86/framework/droiddoc.jar \
-docletpath out/host/$PLATFORM/framework/clearsilver.jar:out/host/$PLATFORM/framework/droiddoc.jar \
-templatedir tools/droiddoc/templates \
-classpath out/target/common/obj/JAVA_LIBRARIES/core_intermediates/classes.jar:out/target/common/obj/JAVA_LIBRARIES/ext_intermediates/classes.jar:out/target/common/obj/JAVA_LIBRARIES/framework_intermediates/classes.jar \
-sourcepath $SRC_DIR:out/target/common/obj/JAVA_LIBRARIES/core_intermediates/classes.jar:out/target/common/obj/JAVA_LIBRARIES/ext_intermediates/classes.jar:out/target/common/obj/JAVA_LIBRARIES/framework_intermediates/classes.jar \

2
tools/droiddoc/test/stubs/run.sh
View file

@ -14,7 +14,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
DIR=tools/droiddoc/test/stubs
DIR=build/tools/droiddoc/test/stubs
pushd $TOP