SOLR-673 -- Modify build file to create javadocs for core, solrj, contrib and "all inclusive"

git-svn-id: https://svn.apache.org/repos/asf/lucene/solr/trunk@682262 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -582,6 +582,8 @@ Build
  4. SOLR-563: Modified the build process to build contrib projects
     (Shalin Shekhar Mangar via Otis Gospodnetic)
 
+ 5. SOLR-673: Modify build file to create javadocs for core, solrj, contrib and "all inclusive" (shalin)
+
 ================== Release 1.2, 20070602 ==================
 
 Upgrading from Solr 1.1

build.xml

@@ -27,20 +27,12 @@
   <!-- solr source files -->
   <property name="src" value="src" />
 
-  <!-- Destination for compiled classes and binaries -->
-  <property name="dest" value="build" />
-
   <!-- Destination for distribution files (demo WAR, src distro, etc.) -->
   <property name="dist" value="dist" />
 
   <!-- Example directory -->
   <property name="example" value="example" />
 
-  <!-- Javadoc properties -->
-  <property name="build.docs" value="${dest}/docs"/>
-  <property name="build.javadoc" value="${build.docs}/api"/>
-  <property name="build.javadoc.solrj" value="${build.docs}/api-solrj"/>
-  
   <!-- JUnit properties -->
   <property name="junit.output.dir" location="${dest}/test-results"/>
   <property name="junit.reports" location="${dest}/test-results/reports"/>
@@ -160,39 +152,60 @@
     </solr-javac>
   </target>
 
-  <target name="core-javadoc" depends="compile,compile-solrj"
-          description="Generates javadoc documentation.">
+  <target name="javadoc-core" depends="compile,compile-solrj"  description="Generates javadoc documentation for core.">
 
-    <mkdir dir="${build.javadoc}"/>
-        
-    <path id="javadoc.classpath">
-       <path refid="compile.classpath"/>
-       <path refid="compile.classpath.solrj"/>
-       <pathelement location="${dest}/client/solrj"/>
-    </path>
+    <sequential>
+      <mkdir dir="${build.javadoc}/core"/>
 
-    <javadoc
-      destdir="${build.javadoc}"
-      author="true"
-      version="true"
-      failonerror="true"
-      use="true"
-      encoding="utf8"
-      access="${javadoc.access}"
-      windowtitle="${Name} ${version} API"
-      doctitle="${Name} ${version} API (${specversion})"
-      bottom="Copyright &amp;copy; ${javadoc.years} The Apache Software Foundation"
-      >
-        <packageset dir="${src}/java"/>
-        <packageset dir="${src}/webapp/src"/>
-        <link href="${javadoc.link.java}"/>
-        <link href="${javadoc.link.junit}"/>
-        <link href="${javadoc.link.lucene}"/>
-        <classpath refid="javadoc.classpath"/>
-    </javadoc>
+      <path id="javadoc.classpath">
+        <path refid="compile.classpath"/>
+        <path refid="compile.classpath.solrj"/>
+        <pathelement location="${dest}/client/solrj"/>
+      </path>
+
+      <invoke-javadoc
+        destdir="${build.javadoc}/core"
+      	title="${Name} ${version} core API (${specversion})">
+        <sources>
+          <packageset dir="src/java"/>
+        </sources>
+      </invoke-javadoc>
+    </sequential>
   </target>
-	
-  <target name="javadoc" depends="core-javadoc, contrib-javadoc">
+
+  <target name="javadoc-all" description="Generate javadoc for core, client and contrib">
+    <sequential>
+      <mkdir dir="${build.javadoc}"/>
+
+      <path id="javadoc.classpath">
+         <path refid="compile.classpath"/>
+         <path refid="compile.classpath.solrj"/>
+         <path refid="compile.classpath.solrj-embedded"/>
+         <pathelement location="${dest}/client/solrj"/>
+      </path>
+
+      <invoke-javadoc destdir="${build.javadoc}">
+        <sources>
+          <packageset dir="${src}/java" />
+          <packageset dir="${src}/webapp/src" />
+          <packageset dir="${src}/webapp/src" />
+          <packageset dir="${solrj-dir}/src" />
+          <packageset dir="contrib/dataimporthandler/src/main/java" />
+
+          <group title="Core" packages="org.apache.*" />
+          <group title="SolrJ" packages="org.apache.solr.client.solrj*" />
+          <group title="contrib: DataImportHandler" packages="org.apache.solr.handler.dataimport*" />
+        </sources>
+      </invoke-javadoc>
+    </sequential>
+  </target>
+
+  <target name="javadoc-contrib" description="Generate javadoc for contrib classes" depends="contrib-build">
+    <contrib-crawl target="javadoc"
+                   failonerror="true"/>
+  </target>
+
+  <target name="javadoc" depends="javadoc-core, javadoc-contrib, javadoc-solrj, javadoc-all">
   </target>
 
   <target name="stub-factories" depends="dist-jar"
@@ -330,31 +343,23 @@
   </target>
   
   
-  <target name="javadoc-solrj" depends="compile"
-          description="Generates solrj javadoc documentation.">
-    <mkdir dir="${build.javadoc.solrj}"/>  
-    <path id="javadoc.classpath.solrj">
-       <path refid="compile.classpath.solrj"/>
-    </path>
-    <javadoc
-      destdir="${build.javadoc.solrj}"
-      author="true"
-      version="true"
-      failonerror="true"
-      use="true"
-      encoding="utf8"
-      access="${javadoc.access}"
-      windowtitle="${Name}-j ${version} API"
-      doctitle="${Name}-j ${version} API (${specversion})"
-      bottom="Copyright &amp;copy; ${javadoc.years} The Apache Software Foundation"
-      >
-        <packageset dir="${solrj-dir}/src" />
-        <link href="${javadoc.link.java}"/>
-        <link href="${javadoc.link.junit}"/>
-        <link href="${javadoc.link.lucene}"/>
-        <classpath refid="compile.classpath.solrj"/>
-        <classpath refid="compile.classpath.solrj-embedded"/>
-    </javadoc>
+  <target name="javadoc-solrj" depends="compile-solrj" description="Generates solrj javadoc documentation.">
+    <sequential>
+      <mkdir dir="${build.javadoc}/solrj"/>
+
+      <path id="javadoc.classpath">
+        <path refid="compile.classpath.solrj"/>
+        <path refid="compile.classpath.solrj-embedded"/>
+      </path>
+
+      <invoke-javadoc
+        destdir="${build.javadoc}/solrj"
+      	title="${Name}-j ${version} API (${specversion})">
+        <sources>
+          <packageset dir="${solrj-dir}/src"/>
+        </sources>
+      </invoke-javadoc>
+    </sequential>
   </target>
   
 

common-build.xml

@@ -20,12 +20,16 @@
     This file is designed for importing into a main build file, and not intended
     for standalone use.
   </description>
+
+  <dirname file="${ant.file.common}" property="common.dir"/>
   
   <!-- Initialize property values: allow easy customization via build.properties -->
   <property file="build.properties" />
 
   <property name="Name" value="Solr" />
 
+  <property name="name" value="${ant.project.name}"/>
+
   <tstamp>
     <format property="year" pattern="yyyy"/>
     <format property="DSTAMP" pattern="yyyy-MM-dd"/>
@@ -63,6 +67,9 @@
   <property name="fullname" value="apache-${ant.project.name}"/>
   <property name="fullnamever" value="apache-${ant.project.name}-${version}"/>
 
+  <!-- Destination for compiled classes and binaries -->
+  <property name="dest" value="build" />
+
   <!-- Javadoc properties -->
   <property name="javadoc.years" value="2006 - ${year}" />
   <property name="javadoc.access" value="protected"/>
@@ -73,6 +80,9 @@
   <property name="javadoc.link.lucene"
             value="http://lucene.apache.org/java/docs/api/"/>
   <property name="javadoc.packages" value="org.apache.solr.*"/>
+  <property name="build.docs" value="${dest}/docs"/>
+  <property name="build.javadoc" value="${common.dir}/${build.docs}/api"/>
+  <property name="build.javadoc.solrj" value="${build.docs}/api-solrj"/>
   
   <!-- JUnit properties -->
   <property name="junit.includes" value="**/Test*.java,**/*Test.java"/>
@@ -147,6 +157,39 @@
       </subant>
     </sequential>
   </macrodef>
+
+  <macrodef name="invoke-javadoc">
+    <element name="sources" optional="yes"/>
+    <attribute name="destdir"/>
+  	<attribute name="title" default="${Name} ${version} API (${specversion})"/>
+    <sequential>
+      <javadoc
+          packagenames="org.apache.solr.*"
+          failonerror="true"
+          destdir="@{destdir}"
+          access="${javadoc.access}"
+          encoding="utf-8"
+          author="true"
+          version="true"
+          use="true"
+          source="${ant.java.version}"
+          link="${javadoc.link.java}"
+          windowtitle="${Name} ${version} API"
+          doctitle="@{title}"
+          bottom="Copyright &amp;copy; ${year} Apache Software Foundation.  All Rights Reserved.">
+        <tag name="todo" description="To Do:"/>
+        <tag name="uml.property" description="UML Property:"/>
+      	<link offline="true" packagelistLoc="${build.javadoc}"/>
+        <link href="${javadoc.link.java}"/>
+        <link href="${javadoc.link.junit}"/>
+        <link href="${javadoc.link.lucene}"/>
+
+        <sources />
+
+        <classpath refid="javadoc.classpath"/>
+      </javadoc>
+   </sequential>
+  </macrodef>
 	
   <target name="contrib-clean"
 	          description="Cleans all contrib modules and their tests">
@@ -162,11 +205,6 @@
     <contrib-crawl target="test" failonerror="true"/>
   </target>
 	
-  <target name="contrib-javadoc" description="Generate javadoc for contrib classes" depends="contrib-build">
-    <contrib-crawl target="javadoc"
-                   failonerror="true"/>
-  </target>
-	
   <target name="dist-contrib" description="Make the contribs ready for distribution">
   	<contrib-crawl target="dist" failonerror="true" />
   </target>

contrib/dataimporthandler/build.xml

@@ -21,8 +21,6 @@
 	
   <property name="solr-path" value="../.." />
 	
-  <property name="javadoc.dir" value="target/javadoc"></property>
-	
   <import file="../../common-build.xml"/>
 
   <description>
@@ -47,7 +45,7 @@
 	
   <target name="init">
   	<mkdir dir="target/classes"/>
-    <mkdir dir="${javadoc.dir}" />
+    <mkdir dir="${build.javadoc}" />
     <ant dir="../../" inheritall="false" target="compile" />
   </target>
 	
@@ -103,27 +101,19 @@
 	
   <target name="javadoc">
    	<sequential>
-       <mkdir dir="${javadoc.dir}/contrib-${fullnamever}"/>
-   	   <javadoc
-   		      destdir="${javadoc.dir}/contrib-${fullnamever}"
-   		      author="true"
-   		      version="true"
-   		      failonerror="true"
-   		      use="true"
-   		      encoding="utf8"
-   		      access="${javadoc.access}"
-   		      windowtitle="${Name} ${version} contrib-${fullnamever} API"
-   		      doctitle="${Name} ${version} API (${specversion})"
-   		      bottom="Copyright &amp;copy; ${javadoc.years} The Apache Software Foundation"
-   		      >
-   		        <packageset dir="src/main/java"/>
-   		        <link href="${javadoc.link.java}"/>
-   		        <link href="${javadoc.link.junit}"/>
-   		        <link href="${javadoc.link.lucene}"/>
-   		        <classpath refid="common.classpath"/>
-   		</javadoc>
-      <jar basedir="${javadoc.dir}/contrib-${fullnamever}" destfile="target/contrib-${fullnamever}-javadoc.jar"/>
-   	  <copy file="target/contrib-${fullnamever}-javadoc.jar" todir="${solr-path}/dist"></copy>
+      <mkdir dir="${build.javadoc}/contrib-${name}"/>
+
+      <path id="javadoc.classpath">
+        <path refid="common.classpath"/>
+      </path>
+
+      <invoke-javadoc
+        destdir="${build.javadoc}/contrib-${name}"
+      	title="${Name} ${version} contrib-${fullnamever} API">
+        <sources>
+          <packageset dir="src/main/java"/>
+        </sources>
+      </invoke-javadoc>
     </sequential>
   </target>