From 4c147329a9e20fc62651a1e43d19ff07d365c9f6 Mon Sep 17 00:00:00 2001
From: hanna <hanna@348d0f76-0448-11de-a6fe-93d51630548a>
Date: Fri, 4 Dec 2009 20:08:41 +0000
Subject: [PATCH] Turn javadoc comments for packages and classes into key/value
 pairs in a properties file.  Embed the properties file in
 GenomeAnalysisTK.jar.  Still no support for actually displaying the archived
 javadoc.  Also change the approach to providing package javadocs: retired the
 deprecated package.html file in favor of Java1.5-style package-info.java.

git-svn-id: file:///humgen/gsa-scr1/gsa-engineering/svn_contents/trunk@2263 348d0f76-0448-11de-a6fe-93d51630548a
---
 build.xml                                     | 61 ++++++++-----
 .../sting/gatk/datasources/package-info.java  |  5 ++
 .../sting/gatk/datasources/package.html       | 11 ---
 .../datasources/providers/package-info.java   |  6 ++
 .../gatk/datasources/providers/package.html   | 12 ---
 .../gatk/datasources/shards/package-info.java |  6 ++
 .../gatk/datasources/shards/package.html      | 12 ---
 .../simpleDataSources/package-info.java       |  6 ++
 .../simpleDataSources/package.html            | 12 ---
 .../sting/gatk/executive/package-info.java    |  4 +
 .../sting/gatk/executive/package.html         | 10 ---
 .../sting/gatk/filters/package-info.java      |  4 +
 .../sting/gatk/filters/package.html           | 34 --------
 .../sting/gatk/iterators/package-info.java    |  4 +
 .../sting/gatk/iterators/package.html         | 10 ---
 .../sting/gatk/package-info.java              |  5 ++
 .../broadinstitute/sting/gatk/package.html    | 11 ---
 .../sting/gatk/refdata/package-info.java      |  5 ++
 .../sting/gatk/refdata/package.html           | 10 ---
 .../sting/gatk/traversals/package-info.java   |  5 ++
 .../sting/gatk/traversals/package.html        | 11 ---
 .../sting/gatk/walkers/package-info.java      |  6 ++
 .../sting/gatk/walkers/package.html           | 13 ---
 .../sting/utils/doc/HelpExtractorDoclet.java  | 87 +++++++++++++++++++
 24 files changed, 181 insertions(+), 169 deletions(-)
 create mode 100644 java/src/org/broadinstitute/sting/gatk/datasources/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/datasources/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/datasources/providers/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/datasources/providers/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/datasources/shards/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/datasources/shards/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/datasources/simpleDataSources/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/datasources/simpleDataSources/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/executive/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/executive/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/filters/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/filters/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/iterators/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/iterators/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/refdata/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/refdata/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/traversals/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/traversals/package.html
 create mode 100644 java/src/org/broadinstitute/sting/gatk/walkers/package-info.java
 delete mode 100644 java/src/org/broadinstitute/sting/gatk/walkers/package.html
 create mode 100644 java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java

diff --git a/build.xml b/build.xml
index 73b0c8d68..217c1b51e 100644
--- a/build.xml
+++ b/build.xml
@@ -2,7 +2,9 @@
     <description>Compile and distribute the Sting toolkit</description>
 
     <property name="source.dir" value="java/src" />
+    <property name="build.dir" value="build" />
     <property name="dist.dir" value="dist" />
+    <property name="help.file" value="${build.dir}/help.properties" />
 
     <property name="single" value="*Test" />
     <property name="singleintegration" value="*IntegrationTest" />
@@ -24,6 +26,25 @@
     <property environment="env"/>
     <property name="target" value="${env.STING_BUILD_TYPE}" />
 
+    <dirset id="source.files" dir="${source.dir}">
+      <patternset>
+	<include name="org/broadinstitute/sting/**"/>
+	<exclude name="**/playground/**" unless="include.playground" />
+	<exclude name="**/oneoffprojects/**" unless="include.oneoffs" />
+      </patternset>
+    </dirset>
+    
+    <patternset id="dependency.mask" includes="*.jar">
+      <exclude name="junit*.jar" />
+      <exclude name="bcel*.jar" />
+    </patternset>
+    
+    <path id="runtime.dependencies">
+      <fileset dir="lib">
+        <patternset refid="dependency.mask" />
+      </fileset>
+    </path>
+
     <!-- ivy properties -->
     <property name="ivy.install.version" value="2.0.0"/>
     <property name="ivy.home" value="${user.home}/.ant"/>
@@ -60,17 +81,6 @@
         </or>
       </condition>
       
-      <patternset id="dependency.mask" includes="*.jar">
-        <exclude name="junit*.jar" />
-        <exclude name="bcel*.jar" />
-      </patternset>
-      
-      <path id="runtime.dependencies">
-        <fileset dir="lib">
-          <patternset refid="dependency.mask" />
-        </fileset>
-      </path>
-      
       <!-- Create the build directory structure used by compile -->
       <mkdir dir="build"/>
     </target>
@@ -84,7 +94,17 @@
       </javac>
     </target>
 
-    <target name="dist" depends="compile"
+    <target name="extracthelp" depends="compile" 
+	    description="Extract help key/value pair file from the JavaDoc tags.">
+      <javadoc doclet="org.broadinstitute.sting.utils.doc.HelpExtractorDoclet"
+	       docletpath="build"
+	       classpathref="runtime.dependencies"
+	       additionalparam="-out ${help.file}">
+	<packageset refid="source.files"/>
+      </javadoc>
+    </target>
+
+    <target name="dist" depends="compile,extracthelp"
             description="generate the distribution">
         <mkdir dir="${dist.dir}"/>
         <delete>
@@ -101,6 +121,7 @@
 
         <jar jarfile="${dist.dir}/GenomeAnalysisTK.jar">
             <fileset dir="build">
+	      <include name="help.properties" />
               <include name="**/gatk/**/*.class" />
               <include name="**/alignment/**/*.class"/>
               <include name="**/oneoffprojects/**/*.class" />
@@ -251,8 +272,8 @@
     
 
     <!-- where to put reports and tests-->
-    <property name="report" value="build/report"/>
-    <property name="test.classes" value="build/testclasses"/>
+    <property name="report" value="${build.dir}/report"/>
+    <property name="test.classes" value="${build.dir}/testclasses"/>
     <property name="test.output" value="${dist.dir}/test"/>
     <property name="test.sources" value="java/test"/>
 
@@ -261,7 +282,7 @@
         <mkdir dir="${report}"/>
         <echo message="Sting: Running test cases!"/>
         <junit printsummary="yes" showoutput="yes" clonevm="yes" haltonfailure="${halt}" failureProperty="test.failure">
-            <jvmarg value="-javaagent:build/TestAgent.jar"/>
+            <jvmarg value="-javaagent:${build.dir}/TestAgent.jar"/>
             <formatter type="${testOutput}" usefile="${usefile}" />
             <classpath>
                 <path refid="runtime.dependencies"/>
@@ -306,7 +327,7 @@
     <!-- this builds the instrumentation library we're going to use for test cases -->
     <target name="agent" description="build the agent">
         <echo message="Sting: Creating test agent!"/>
-        <jar jarfile="build/TestAgent.jar">
+        <jar jarfile="${build.dir}/TestAgent.jar">
             <fileset dir="build">
             <include name="**/TrivialInstrumenter.class" />
           </fileset>
@@ -322,13 +343,7 @@
       <mkdir dir="javadoc"/>
       <javadoc destdir="javadoc"
                classpathref="runtime.dependencies">
-        <fileset dir="${source.dir}">
-          <patternset>
-            <include name="**/*.java"/>
-            <exclude name="**/playground/**" unless="include.playground"/>
-            <exclude name="**/oneoffprojects/**" unless="include.oneoffs"/>
-         </patternset>
-        </fileset>
+        <packageset refid="source.files"/>
       </javadoc>
     </target>
 
diff --git a/java/src/org/broadinstitute/sting/gatk/datasources/package-info.java b/java/src/org/broadinstitute/sting/gatk/datasources/package-info.java
new file mode 100644
index 000000000..abb2d0b84
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/datasources/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Provides efficient access to GATK primary data sources 
+ * such as SAM files, fasta files, and reference-ordered data.
+ */
+package org.broadinstitute.sting.gatk.datasources;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/datasources/package.html b/java/src/org/broadinstitute/sting/gatk/datasources/package.html
deleted file mode 100644
index c60831f50..000000000
--- a/java/src/org/broadinstitute/sting/gatk/datasources/package.html
+++ /dev/null
@@ -1,11 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Provides efficient access to GATK primary data sources 
-such as SAM files, fasta files, and reference-ordered data.
-
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/datasources/providers/package-info.java b/java/src/org/broadinstitute/sting/gatk/datasources/providers/package-info.java
new file mode 100644
index 000000000..1b98e36cf
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/datasources/providers/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Provides a bridge from the block-at-a-time data access provided by
+ * the datasource system to the locus / read-at-a-time data access
+ * required by the traversal engine.
+ */
+package org.broadinstitute.sting.gatk.datasources.providers;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/datasources/providers/package.html b/java/src/org/broadinstitute/sting/gatk/datasources/providers/package.html
deleted file mode 100644
index eddb660b2..000000000
--- a/java/src/org/broadinstitute/sting/gatk/datasources/providers/package.html
+++ /dev/null
@@ -1,12 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Provides a bridge from the block-at-a-time data access provided by
-the datasource system to the locus / read-at-a-time data access
-required by the traversal engine.
-
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/datasources/shards/package-info.java b/java/src/org/broadinstitute/sting/gatk/datasources/shards/package-info.java
new file mode 100644
index 000000000..7d209f9c6
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/datasources/shards/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Divides core input data into manageable blocks, each representing
+ * a subsection of data that is small enough to be processed by a single
+ * worker.
+ */
+package org.broadinstitute.sting.gatk.datasources.shards;
diff --git a/java/src/org/broadinstitute/sting/gatk/datasources/shards/package.html b/java/src/org/broadinstitute/sting/gatk/datasources/shards/package.html
deleted file mode 100644
index e13aba69a..000000000
--- a/java/src/org/broadinstitute/sting/gatk/datasources/shards/package.html
+++ /dev/null
@@ -1,12 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Divides core input data into manageable blocks, each representing
-a subsection of data that is small enough to be processed by a single
-worker.
-
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/datasources/simpleDataSources/package-info.java b/java/src/org/broadinstitute/sting/gatk/datasources/simpleDataSources/package-info.java
new file mode 100644
index 000000000..e0f73e794
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/datasources/simpleDataSources/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Retrieves core GATK data, given a shard which represents a contiguous
+ * subsequence of core GATK data (reads, reference, or reference-ordered
+ * data).
+ */
+package org.broadinstitute.sting.gatk.datasources.simpleDataSources;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/datasources/simpleDataSources/package.html b/java/src/org/broadinstitute/sting/gatk/datasources/simpleDataSources/package.html
deleted file mode 100644
index 21587f902..000000000
--- a/java/src/org/broadinstitute/sting/gatk/datasources/simpleDataSources/package.html
+++ /dev/null
@@ -1,12 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Retrieves core GATK data, given a shard which represents a contiguous
-subsequence of core GATK data (reads, reference, or reference-ordered
-data).
-
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/executive/package-info.java b/java/src/org/broadinstitute/sting/gatk/executive/package-info.java
new file mode 100644
index 000000000..2ceb2ca14
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/executive/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Manages individual analyses by shattering data, pushing individual shards to the traversal engines, and gathering results and presenting them to the user.
+ */
+package org.broadinstitute.sting.gatk.executive;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/executive/package.html b/java/src/org/broadinstitute/sting/gatk/executive/package.html
deleted file mode 100644
index 5c9d96264..000000000
--- a/java/src/org/broadinstitute/sting/gatk/executive/package.html
+++ /dev/null
@@ -1,10 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Manages individual analyses by shattering data, pushing individual shards to the traversal engines, and gathering results and presenting them to the user.
-
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/filters/package-info.java b/java/src/org/broadinstitute/sting/gatk/filters/package-info.java
new file mode 100644
index 000000000..efd3a6db5
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/filters/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Provides a commonly used set of filters for determining which data should and should not be applied.
+ */
+package org.broadinstitute.sting.gatk.filters;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/filters/package.html b/java/src/org/broadinstitute/sting/gatk/filters/package.html
deleted file mode 100644
index a2519a659..000000000
--- a/java/src/org/broadinstitute/sting/gatk/filters/package.html
+++ /dev/null
@@ -1,34 +0,0 @@
-<!--
-  ~ Copyright (c) 2009 The Broad Institute
-  ~ Permission is hereby granted, free of charge, to any person
-  ~ obtaining a copy of this software and associated documentation
-  ~ files (the "Software"), to deal in the Software without
-  ~ restriction, including without limitation the rights to use,
-  ~ copy, modify, merge, publish, distribute, sublicense, and/or sell
-  ~ copies of the Software, and to permit persons to whom the
-  ~ Software is furnished to do so, subject to the following
-  ~ conditions:
-  ~
-  ~ The above copyright notice and this permission notice shall be
-  ~ included in all copies or substantial portions of the Software.
-  ~
-  ~ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-  ~ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-  ~ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-  ~ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-  ~ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-  ~ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-  ~ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-  ~ OTHER DEALINGS IN THE SOFTWARE.
-  -->
-
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-        "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-    <title></title>
-</head>
-<body>
-Provides a commonly used set of filters for determining which data should and should not be applied.
-</body>
-</html>
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/iterators/package-info.java b/java/src/org/broadinstitute/sting/gatk/iterators/package-info.java
new file mode 100644
index 000000000..221efd50c
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/iterators/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Tools for iterating over different views of GATK data.
+ */
+package org.broadinstitute.sting.gatk.iterators;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/iterators/package.html b/java/src/org/broadinstitute/sting/gatk/iterators/package.html
deleted file mode 100644
index d14105052..000000000
--- a/java/src/org/broadinstitute/sting/gatk/iterators/package.html
+++ /dev/null
@@ -1,10 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Tools for iterating over different views of GATK data.
-
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/package-info.java b/java/src/org/broadinstitute/sting/gatk/package-info.java
new file mode 100644
index 000000000..4110d8c80
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Provides map/reduce application framework highly optimized for
+ * analysis of sequencing data.
+ */
+package org.broadinstitute.sting.gatk;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/package.html b/java/src/org/broadinstitute/sting/gatk/package.html
deleted file mode 100644
index 677a9b96f..000000000
--- a/java/src/org/broadinstitute/sting/gatk/package.html
+++ /dev/null
@@ -1,11 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Provides map/reduce application framework highly optimized for
-analysis of sequencing data.
-
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/refdata/package-info.java b/java/src/org/broadinstitute/sting/gatk/refdata/package-info.java
new file mode 100644
index 000000000..0c9e084f3
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/refdata/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Reads and preprocesses the various types of data represented by the
+ * GATK.
+ */
+package org.broadinstitute.sting.gatk.refdata;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/refdata/package.html b/java/src/org/broadinstitute/sting/gatk/refdata/package.html
deleted file mode 100644
index 0c6a55319..000000000
--- a/java/src/org/broadinstitute/sting/gatk/refdata/package.html
+++ /dev/null
@@ -1,10 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Reads and preprocesses the various types of data represented by the
-GATK.
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/traversals/package-info.java b/java/src/org/broadinstitute/sting/gatk/traversals/package-info.java
new file mode 100644
index 000000000..171c27df6
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/traversals/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Traverses over a shard of data, performing a mini-map/reduce on that
+ * dataset.
+ */
+package org.broadinstitute.sting.gatk.traversals;
\ No newline at end of file
diff --git a/java/src/org/broadinstitute/sting/gatk/traversals/package.html b/java/src/org/broadinstitute/sting/gatk/traversals/package.html
deleted file mode 100644
index 82ff0a1f9..000000000
--- a/java/src/org/broadinstitute/sting/gatk/traversals/package.html
+++ /dev/null
@@ -1,11 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Traverses over a shard of data, performing a mini-map/reduce on that
-dataset.
-
-</body>
-</html>
diff --git a/java/src/org/broadinstitute/sting/gatk/walkers/package-info.java b/java/src/org/broadinstitute/sting/gatk/walkers/package-info.java
new file mode 100644
index 000000000..8d118861f
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/gatk/walkers/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Runs the desired analysis on the smallest meaningful subset of the
+ * dataset.  Traditionally, the smallest subset is either an individual 
+ * locus or read.
+ */
+package org.broadinstitute.sting.gatk.walkers;
diff --git a/java/src/org/broadinstitute/sting/gatk/walkers/package.html b/java/src/org/broadinstitute/sting/gatk/walkers/package.html
deleted file mode 100644
index 9f3a8983e..000000000
--- a/java/src/org/broadinstitute/sting/gatk/walkers/package.html
+++ /dev/null
@@ -1,13 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-<head>
-</head>
-<body bgcolor="white">
-
-Runs the desired analysis on the smallest meaningful subset of the
-dataset.  Traditionally, the smallest subset is either an individual 
-locus or read.
-
-</body>
-</html>
-
diff --git a/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java b/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java
new file mode 100644
index 000000000..354cdaa5c
--- /dev/null
+++ b/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java
@@ -0,0 +1,87 @@
+package org.broadinstitute.sting.utils.doc;
+
+import com.sun.javadoc.RootDoc;
+import com.sun.javadoc.PackageDoc;
+import com.sun.javadoc.ClassDoc;
+
+import java.util.HashSet;
+import java.util.Set;
+import java.util.Scanner;
+import java.io.PrintStream;
+import java.io.FileNotFoundException;
+
+/**
+ * Extracts certain types of javadoc (specifically package and class descriptions) and makes them available
+ * to applications at runtime.
+ *
+ * @author mhanna
+ * @version 0.1
+ */
+public class HelpExtractorDoclet {
+    /**
+     * Extracts the contents of certain types of javadoc and adds them to an XML file.
+     * @param rootDoc The documentation root.
+     * @return Whether the JavaDoc run succeeded.
+     */
+    public static boolean start(RootDoc rootDoc) throws FileNotFoundException {
+        PrintStream out = System.out;
+
+        for(String[] options: rootDoc.options()) {
+            if(options[0].equals("-out"))
+                out = new PrintStream(options[1]);
+        }
+
+        // Cache packages as we see them, since there's no direct way to iterate over packages.
+        Set<PackageDoc> packages = new HashSet<PackageDoc>();
+
+        for(ClassDoc currentClass: rootDoc.classes()) {
+            PackageDoc containingPackage = currentClass.containingPackage();
+            packages.add(containingPackage);
+            String className = containingPackage.name().length() > 0 ?
+                    String.format("%s.%s",containingPackage.name(),currentClass.name()) :
+                    String.format("%s",currentClass.name());
+            String commentText = formatText(currentClass.commentText());
+
+            if(commentText.length() > 0)
+                out.printf("%s=%s%n",className,commentText);
+        }
+
+        for(PackageDoc currentPackage: packages) {
+            String commentText = formatText(currentPackage.commentText());
+            if(commentText.length() > 0)
+                out.printf("%s=%s%n",currentPackage.name(),commentText);
+        }
+
+        return true;
+    }
+
+    /**
+     * Validate the given options against 
+     * @param option
+     * @return
+     */
+    public static int optionLength(String option) {
+        if(option.equals("-out")) {
+            return 2;
+        }
+        return 0;
+    }
+
+    /**
+     * Format text for consumption by the properties file.
+     * @param text Text to format.
+     * @return Formatted text; string trimmed, newlines removed.
+     */
+    private static String formatText(String text) {
+        Scanner scanner = new Scanner(text);
+        StringBuilder output = new StringBuilder();
+
+        while(scanner.hasNextLine()) {
+            if(output.length() > 0)
+                output.append(' ');
+            output.append(scanner.nextLine().trim());
+        }
+
+        return output.toString();    
+    }
+}