Generate documentation based on annotations attached to classes and methods

Allow users to pass in a text file of the format:
   annotationname:Documentation String
   annotation2:More Documentation
that will get inserted into the docs when a class or method has
that annotation.

Bug: 19931569
Change-Id: Ic2334dd2fcba638526cf2d67e25e27cf8e39b6fe

3 files changed, 59 insertions, 0 deletions

diff --git a/src/com/google/doclava/ClassInfo.java b/src/com/google/doclava/ClassInfo.java
index 14cd99c..a5ee7d4 100644
--- a/src/com/google/doclava/ClassInfo.java
+++ b/src/com/google/doclava/ClassInfo.java
@@ -1234,6 +1234,17 @@ public class ClassInfo extends DocInfo implements ContainerInfo, Comparable, Sco
       data.setValue("class.abstract", "abstract");
     }
 
+    int numAnnotationDocumentation = 0;
+    for (AnnotationInstanceInfo aii : annotations()) {
+      String annotationDocumentation = Doclava.getDocumentationStringForAnnotation(
+          aii.type().qualifiedName());
+      if (annotationDocumentation != null) {
+        data.setValue("class.annotationdocumentation." + numAnnotationDocumentation + ".text",
+            annotationDocumentation);
+        numAnnotationDocumentation++;
+      }
+    }
+
     ArrayList<AnnotationInstanceInfo> showAnnos = getShowAnnotationsIncludeOuters();
     AnnotationInstanceInfo.makeLinkListHDF(
       data,
diff --git a/src/com/google/doclava/Doclava.java b/src/com/google/doclava/Doclava.java
index 6e46123..94331ee 100644
--- a/src/com/google/doclava/Doclava.java
+++ b/src/com/google/doclava/Doclava.java
@@ -95,6 +95,9 @@ public class Doclava {
   private static boolean generateDocs = true;
   private static boolean parseComments = false;
   private static String yamlNavFile = null;
+  public static boolean documentAnnotations = false;
+  public static String documentAnnotationsPath = null;
+  public static Map<String, String> annotationDocumentationMap = null;
 
   public static JSilver jSilver = null;
 
@@ -273,6 +276,9 @@ public class Doclava {
         // Don't copy the doclava assets to devsite output (ie use proj assets only)
         includeDefaultAssets = false;
         outputPathHtmlDirs = outputPathHtmlDirs + "/" + devsiteRoot;
+      } else if (a[0].equals("-documentannotations")) {
+        documentAnnotations = true;
+        documentAnnotationsPath = a[1];
       }
     }
 
@@ -663,6 +669,9 @@ public class Doclava {
     if (option.equals("-metadataDebug")) {
       return 1;
     }
+    if (option.equals("-documentannotations")) {
+      return 2;
+    }
     return 0;
   }
   public static boolean validOptions(String[][] options, DocErrorReporter r) {
@@ -1816,4 +1825,31 @@ public class Doclava {
     }
   }
 
+  public static String getDocumentationStringForAnnotation(String annotationName) {
+    if (!documentAnnotations) return null;
+    if (annotationDocumentationMap == null) {
+      // parse the file for map
+      annotationDocumentationMap = new HashMap<String, String>();
+      try {
+        BufferedReader in = new BufferedReader(
+            new FileReader(documentAnnotationsPath));
+        try {
+          String line = in.readLine();
+          String[] split;
+          while (line != null) {
+            split = line.split(":");
+            annotationDocumentationMap.put(split[0], split[1]);
+            line = in.readLine();
+          }
+        } finally {
+          in.close();
+        }
+      } catch (IOException e) {
+        System.err.println("Unable to open annotations documentation file for reading: "
+            + documentAnnotationsPath);
+      }
+    }
+    return annotationDocumentationMap.get(annotationName);
+  }
+
 }
diff --git a/src/com/google/doclava/MethodInfo.java b/src/com/google/doclava/MethodInfo.java
index eb360cd..f1659f3 100644
--- a/src/com/google/doclava/MethodInfo.java
+++ b/src/com/google/doclava/MethodInfo.java
@@ -592,6 +592,18 @@ public class MethodInfo extends MemberInfo implements AbstractMethodInfo, Resolv
       TypeInfo.makeHDF(data, base + ".generic.typeArguments", mTypeParameters, false);
     }
 
+    int numAnnotationDocumentation = 0;
+    for (AnnotationInstanceInfo aii : annotations()) {
+      String annotationDocumentation = Doclava.getDocumentationStringForAnnotation(
+          aii.type().qualifiedName());
+      if (annotationDocumentation != null) {
+        data.setValue(base + ".annotationdocumentation." + numAnnotationDocumentation + ".text",
+            annotationDocumentation);
+        numAnnotationDocumentation++;
+      }
+    }
+
+
     AnnotationInstanceInfo.makeLinkListHDF(
       data,
       base + ".showAnnotations",