monkeyrunner/src/com/android/monkeyrunner/MonkeyRunnerHelp.java - platform/sdk - Git at Google

 /*
  * Copyright (C) 2010 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package com.android.monkeyrunner;

 import com.google.clearsilver.jsilver.JSilver;
 import com.google.clearsilver.jsilver.data.Data;
 import com.google.clearsilver.jsilver.resourceloader.ClassLoaderResourceLoader;
 import com.google.clearsilver.jsilver.resourceloader.ResourceLoader;
 import com.google.common.base.Function;
 import com.google.common.base.Predicate;
 import com.google.common.collect.Collections2;
 import com.google.common.collect.Lists;
 import com.google.common.collect.Sets;

 import com.android.monkeyrunner.doc.MonkeyRunnerExported;

 import java.io.IOException;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Field;
 import java.lang.reflect.Member;
 import java.lang.reflect.Method;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Comparator;
 import java.util.List;
 import java.util.Set;

 /**
  * Utility class for generating inline help documentation
  */
 public final class MonkeyRunnerHelp {
     private MonkeyRunnerHelp() { }

     private static final String HELP = "help";
     private static final String NAME = "name";
     private static final String DOC = "doc";
     private static final String ARGUMENT = "argument";
     private static final String RETURNS = "returns";
     private static final String TYPE = "type";

     // Enum used to describe documented types.
     private enum Type {
         ENUM, FIELD, METHOD
     }

     private static void getAllExportedClasses(Set<Field> fields,
             Set<Method> methods,
             Set<Constructor<?>> constructors,
             Set<Class<?>> enums) {
         final Set<Class<?>> classesVisited = Sets.newHashSet();
         Set<Class<?>> classesToVisit = Sets.newHashSet();
         classesToVisit.add(MonkeyRunner.class);

         Predicate<Class<?>> haventSeen = new Predicate<Class<?>>() {
             public boolean apply(Class<?> clz) {
                 return !classesVisited.contains(clz);
             }
         };

         while (!classesToVisit.isEmpty()) {
             classesVisited.addAll(classesToVisit);

             List<Class<?>> newClasses = Lists.newArrayList();
             for (Class<?> clz : classesToVisit) {
                 // See if the class itself is annotated and is an enum
                 if (clz.isEnum() && clz.isAnnotationPresent(MonkeyRunnerExported.class)) {
                     enums.add(clz);
                 }

                 // Constructors
                 for (Constructor<?> c : clz.getConstructors()) {
                     newClasses.addAll(Collections2.filter(Arrays.asList(c.getParameterTypes()),
                             haventSeen));
                     if (c.isAnnotationPresent(MonkeyRunnerExported.class)) {
                         constructors.add(c);
                     }
                 }

                 // Fields
                 for (Field f : clz.getFields()) {
                     if (haventSeen.apply(f.getClass())) {
                         newClasses.add(f.getClass());
                     }
                     if (f.isAnnotationPresent(MonkeyRunnerExported.class)) {
                         fields.add(f);
                     }
                 }

                 // Methods
                 for (Method m : clz.getMethods()) {
                     newClasses.addAll(Collections2.filter(Arrays.asList(m.getParameterTypes()),
                             haventSeen));
                     if (haventSeen.apply(m.getReturnType())) {
                         newClasses.add(m.getReturnType());
                     }

                     if (m.isAnnotationPresent(MonkeyRunnerExported.class)) {
                         methods.add(m);
                     }
                 }

                 // Containing classes
                 for (Class<?> toAdd : clz.getClasses()) {
                     if (haventSeen.apply(toAdd)) {
                         newClasses.add(toAdd);
                     }
                 }
             }

             classesToVisit.clear();
             classesToVisit.addAll(newClasses);
         }
     }

     private static Comparator<Member> MEMBER_SORTER = new Comparator<Member>() {
         public int compare(Member o1, Member o2) {
             return o1.getName().compareTo(o2.getName());
         }
     };

     private static Comparator<Class<?>> CLASS_SORTER = new Comparator<Class<?>>() {
         public int compare(Class<?> o1, Class<?> o2) {
             return o1.getName().compareTo(o2.getName());
         }
     };

     public static String helpString(String format) {
         ResourceLoader resourceLoader = new ClassLoaderResourceLoader(
             MonkeyRunner.class.getClassLoader(), "com/android/monkeyrunner");
         JSilver jsilver = new JSilver(resourceLoader);

         // Quick check for support formats
         if ("html".equals(format) || "text".equals(format) || "sdk-docs".equals(format)) {
             try {
                 Data hdf = buildHelpHdf(jsilver);
                 return jsilver.render(format + ".cs", hdf);
             } catch (IOException e) {
                 return "";
             }
         } else if ("hdf".equals(format)) {
             Data hdf = buildHelpHdf(jsilver);
             return hdf.toString();
         }
         return "";
     }

     /**
      * Parse the value string into paragraphs and put them into the
      * HDF under this specified prefix.  Each paragraph will appear
      * numbered under the prefix.  For example:
      *
      * paragraphsIntoHDF("a.b.c", ....)
      *
      * Will create paragraphs under "a.b.c.0", "a.b.c.1", etc.
      *
      * @param prefix The prefix to put the values under.
      * @param value the value to parse paragraphs from.
      * @param hdf the HDF to add the entries to.
      */
     private static void paragraphsIntoHDF(String prefix, String value, Data hdf) {
         String paragraphs[] = value.split("\n");
         int x = 0;
         for (String para : paragraphs) {
             hdf.setValue(prefix + "." + x, para);
             x++;
         }
     }

     private static Data buildHelpHdf(JSilver jsilver) {
         Data hdf = jsilver.createData();
         int outputItemCount = 0;

         Set<Field> fields = Sets.newTreeSet(MEMBER_SORTER);
         Set<Method> methods = Sets.newTreeSet(MEMBER_SORTER);
         Set<Constructor<?>> constructors = Sets.newTreeSet(MEMBER_SORTER);
         Set<Class<?>> classes = Sets.newTreeSet(CLASS_SORTER);
         getAllExportedClasses(fields, methods, constructors, classes);

         for (Class<?> clz : classes) {
             String prefix = HELP + "." + outputItemCount + ".";

             hdf.setValue(prefix + NAME, clz.getCanonicalName());
             MonkeyRunnerExported annotation = clz.getAnnotation(MonkeyRunnerExported.class);
             paragraphsIntoHDF(prefix + DOC, annotation.doc(), hdf);
             hdf.setValue(prefix + TYPE, Type.ENUM.name());

             // Now go through the enumeration constants
             Object[] constants = clz.getEnumConstants();
             String[] argDocs = annotation.argDocs();
             if (constants.length > 0) {
                 for (int x = 0; x < constants.length; x++) {
                     String argPrefix = prefix + ARGUMENT + "." + x + ".";
                     hdf.setValue(argPrefix + NAME, constants[x].toString());
                     if (argDocs.length > x) {
                         paragraphsIntoHDF(argPrefix + DOC, argDocs[x], hdf);
                     }
                 }
             }
             outputItemCount++;
         }

         for (Method m : methods) {
             String prefix = HELP + "." + outputItemCount + ".";

             MonkeyRunnerExported annotation = m.getAnnotation(MonkeyRunnerExported.class);
             String className = m.getDeclaringClass().getCanonicalName();
             String methodName = className + "." + m.getName();
             hdf.setValue(prefix + NAME, methodName);
             paragraphsIntoHDF(prefix + DOC, annotation.doc(), hdf);
             if (annotation.args().length > 0) {
                 String[] argDocs = annotation.argDocs();
                 String[] aargs = annotation.args();
                 for (int x = 0; x < aargs.length; x++) {
                     String argPrefix = prefix + ARGUMENT + "." + x + ".";

                     hdf.setValue(argPrefix + NAME, aargs[x]);
                     if (argDocs.length > x) {
                         paragraphsIntoHDF(argPrefix + DOC, argDocs[x], hdf);
                     }
                 }
             }
             if (!"".equals(annotation.returns())) {
                 paragraphsIntoHDF(prefix + RETURNS, annotation.returns(), hdf);
             }
             outputItemCount++;
         }

         return hdf;
     }

     public static Collection<String> getAllDocumentedClasses() {
         Set<Field> fields = Sets.newTreeSet(MEMBER_SORTER);
         Set<Method> methods = Sets.newTreeSet(MEMBER_SORTER);
         Set<Constructor<?>> constructors = Sets.newTreeSet(MEMBER_SORTER);
         Set<Class<?>> classes = Sets.newTreeSet(CLASS_SORTER);
         getAllExportedClasses(fields, methods, constructors, classes);

         // The classes object only captures classes that are specifically exporter, which isn't
         // good enough.  So go through all the fields, methods, etc. and collect those classes as
         // as well
         Set<Class<?>> allClasses = Sets.newHashSet();
         allClasses.addAll(classes);
         for (Field f : fields) {
             allClasses.add(f.getDeclaringClass());
         }
         for (Method m : methods) {
             allClasses.add(m.getDeclaringClass());
         }
         for (Constructor<?> constructor : constructors) {
             allClasses.add(constructor.getDeclaringClass());
         }

         // And transform that collection into a list of simple names.
         return Collections2.transform(allClasses, new Function<Class<?>, String>() {
             @Override
             public String apply(Class<?> clz) {
                 return clz.getName();
             }
         });
     }
 }
	/*
	* Copyright (C) 2010 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/
	package com.android.monkeyrunner;

	import com.google.clearsilver.jsilver.JSilver;
	import com.google.clearsilver.jsilver.data.Data;
	import com.google.clearsilver.jsilver.resourceloader.ClassLoaderResourceLoader;
	import com.google.clearsilver.jsilver.resourceloader.ResourceLoader;
	import com.google.common.base.Function;
	import com.google.common.base.Predicate;
	import com.google.common.collect.Collections2;
	import com.google.common.collect.Lists;
	import com.google.common.collect.Sets;

	import com.android.monkeyrunner.doc.MonkeyRunnerExported;

	import java.io.IOException;
	import java.lang.reflect.Constructor;
	import java.lang.reflect.Field;
	import java.lang.reflect.Member;
	import java.lang.reflect.Method;
	import java.util.Arrays;
	import java.util.Collection;
	import java.util.Comparator;
	import java.util.List;
	import java.util.Set;

	/**
	* Utility class for generating inline help documentation
	*/
	public final class MonkeyRunnerHelp {
	private MonkeyRunnerHelp() { }

	private static final String HELP = "help";
	private static final String NAME = "name";
	private static final String DOC = "doc";
	private static final String ARGUMENT = "argument";
	private static final String RETURNS = "returns";
	private static final String TYPE = "type";

	// Enum used to describe documented types.
	private enum Type {
	ENUM, FIELD, METHOD
	}

	private static void getAllExportedClasses(Set<Field> fields,
	Set<Method> methods,
	Set<Constructor<?>> constructors,
	Set<Class<?>> enums) {
	final Set<Class<?>> classesVisited = Sets.newHashSet();
	Set<Class<?>> classesToVisit = Sets.newHashSet();
	classesToVisit.add(MonkeyRunner.class);

	Predicate<Class<?>> haventSeen = new Predicate<Class<?>>() {
	public boolean apply(Class<?> clz) {
	return !classesVisited.contains(clz);
	}
	};

	while (!classesToVisit.isEmpty()) {
	classesVisited.addAll(classesToVisit);

	List<Class<?>> newClasses = Lists.newArrayList();
	for (Class<?> clz : classesToVisit) {
	// See if the class itself is annotated and is an enum
	if (clz.isEnum() && clz.isAnnotationPresent(MonkeyRunnerExported.class)) {
	enums.add(clz);
	}

	// Constructors
	for (Constructor<?> c : clz.getConstructors()) {
	newClasses.addAll(Collections2.filter(Arrays.asList(c.getParameterTypes()),
	haventSeen));
	if (c.isAnnotationPresent(MonkeyRunnerExported.class)) {
	constructors.add(c);
	}
	}

	// Fields
	for (Field f : clz.getFields()) {
	if (haventSeen.apply(f.getClass())) {
	newClasses.add(f.getClass());
	}
	if (f.isAnnotationPresent(MonkeyRunnerExported.class)) {
	fields.add(f);
	}
	}

	// Methods
	for (Method m : clz.getMethods()) {
	newClasses.addAll(Collections2.filter(Arrays.asList(m.getParameterTypes()),
	haventSeen));
	if (haventSeen.apply(m.getReturnType())) {
	newClasses.add(m.getReturnType());
	}

	if (m.isAnnotationPresent(MonkeyRunnerExported.class)) {
	methods.add(m);
	}
	}

	// Containing classes
	for (Class<?> toAdd : clz.getClasses()) {
	if (haventSeen.apply(toAdd)) {
	newClasses.add(toAdd);
	}
	}
	}

	classesToVisit.clear();
	classesToVisit.addAll(newClasses);
	}
	}

	private static Comparator<Member> MEMBER_SORTER = new Comparator<Member>() {
	public int compare(Member o1, Member o2) {
	return o1.getName().compareTo(o2.getName());
	}
	};

	private static Comparator<Class<?>> CLASS_SORTER = new Comparator<Class<?>>() {
	public int compare(Class<?> o1, Class<?> o2) {
	return o1.getName().compareTo(o2.getName());
	}
	};

	public static String helpString(String format) {
	ResourceLoader resourceLoader = new ClassLoaderResourceLoader(
	MonkeyRunner.class.getClassLoader(), "com/android/monkeyrunner");
	JSilver jsilver = new JSilver(resourceLoader);

	// Quick check for support formats
	if ("html".equals(format) \|\| "text".equals(format) \|\| "sdk-docs".equals(format)) {
	try {
	Data hdf = buildHelpHdf(jsilver);
	return jsilver.render(format + ".cs", hdf);
	} catch (IOException e) {
	return "";
	}
	} else if ("hdf".equals(format)) {
	Data hdf = buildHelpHdf(jsilver);
	return hdf.toString();
	}
	return "";
	}

	/**
	* Parse the value string into paragraphs and put them into the
	* HDF under this specified prefix. Each paragraph will appear
	* numbered under the prefix. For example:
	*
	* paragraphsIntoHDF("a.b.c", ....)
	*
	* Will create paragraphs under "a.b.c.0", "a.b.c.1", etc.
	*
	* @param prefix The prefix to put the values under.
	* @param value the value to parse paragraphs from.
	* @param hdf the HDF to add the entries to.
	*/
	private static void paragraphsIntoHDF(String prefix, String value, Data hdf) {
	String paragraphs[] = value.split("\n");
	int x = 0;
	for (String para : paragraphs) {
	hdf.setValue(prefix + "." + x, para);
	x++;
	}
	}

	private static Data buildHelpHdf(JSilver jsilver) {
	Data hdf = jsilver.createData();
	int outputItemCount = 0;

	Set<Field> fields = Sets.newTreeSet(MEMBER_SORTER);
	Set<Method> methods = Sets.newTreeSet(MEMBER_SORTER);
	Set<Constructor<?>> constructors = Sets.newTreeSet(MEMBER_SORTER);
	Set<Class<?>> classes = Sets.newTreeSet(CLASS_SORTER);
	getAllExportedClasses(fields, methods, constructors, classes);

	for (Class<?> clz : classes) {
	String prefix = HELP + "." + outputItemCount + ".";

	hdf.setValue(prefix + NAME, clz.getCanonicalName());
	MonkeyRunnerExported annotation = clz.getAnnotation(MonkeyRunnerExported.class);
	paragraphsIntoHDF(prefix + DOC, annotation.doc(), hdf);
	hdf.setValue(prefix + TYPE, Type.ENUM.name());

	// Now go through the enumeration constants
	Object[] constants = clz.getEnumConstants();
	String[] argDocs = annotation.argDocs();
	if (constants.length > 0) {
	for (int x = 0; x < constants.length; x++) {
	String argPrefix = prefix + ARGUMENT + "." + x + ".";
	hdf.setValue(argPrefix + NAME, constants[x].toString());
	if (argDocs.length > x) {
	paragraphsIntoHDF(argPrefix + DOC, argDocs[x], hdf);
	}
	}
	}
	outputItemCount++;
	}

	for (Method m : methods) {
	String prefix = HELP + "." + outputItemCount + ".";

	MonkeyRunnerExported annotation = m.getAnnotation(MonkeyRunnerExported.class);
	String className = m.getDeclaringClass().getCanonicalName();
	String methodName = className + "." + m.getName();
	hdf.setValue(prefix + NAME, methodName);
	paragraphsIntoHDF(prefix + DOC, annotation.doc(), hdf);
	if (annotation.args().length > 0) {
	String[] argDocs = annotation.argDocs();
	String[] aargs = annotation.args();
	for (int x = 0; x < aargs.length; x++) {
	String argPrefix = prefix + ARGUMENT + "." + x + ".";

	hdf.setValue(argPrefix + NAME, aargs[x]);
	if (argDocs.length > x) {
	paragraphsIntoHDF(argPrefix + DOC, argDocs[x], hdf);
	}
	}
	}
	if (!"".equals(annotation.returns())) {
	paragraphsIntoHDF(prefix + RETURNS, annotation.returns(), hdf);
	}
	outputItemCount++;
	}

	return hdf;
	}

	public static Collection<String> getAllDocumentedClasses() {
	Set<Field> fields = Sets.newTreeSet(MEMBER_SORTER);
	Set<Method> methods = Sets.newTreeSet(MEMBER_SORTER);
	Set<Constructor<?>> constructors = Sets.newTreeSet(MEMBER_SORTER);
	Set<Class<?>> classes = Sets.newTreeSet(CLASS_SORTER);
	getAllExportedClasses(fields, methods, constructors, classes);

	// The classes object only captures classes that are specifically exporter, which isn't
	// good enough. So go through all the fields, methods, etc. and collect those classes as
	// as well
	Set<Class<?>> allClasses = Sets.newHashSet();
	allClasses.addAll(classes);
	for (Field f : fields) {
	allClasses.add(f.getDeclaringClass());
	}
	for (Method m : methods) {
	allClasses.add(m.getDeclaringClass());
	}
	for (Constructor<?> constructor : constructors) {
	allClasses.add(constructor.getDeclaringClass());
	}

	// And transform that collection into a list of simple names.
	return Collections2.transform(allClasses, new Function<Class<?>, String>() {
	@Override
	public String apply(Class<?> clz) {
	return clz.getName();
	}
	});
	}
	}