[jira] [Created] (GEODE-572) Generate separate javadocs for public API and internal API

[Dan Smith (JIRA)]

Dan Smith created GEODE-572:
-------------------------------

             Summary: Generate separate javadocs for public API and internal API
                 Key: GEODE-572
                 URL: https://issues.apache.org/jira/browse/GEODE-572
             Project: Geode
          Issue Type: Sub-task
            Reporter: Dan Smith


The javadocs that most geode users are interested in should only include the 
public API for geode. 

We should exclude the internal directories from the public javadocs. It's 
probably still useful to generate internal javadocs for the whole product, but 
those should not be docs we direct users too.

For reference, here's the javadoc task from the old gemfire ant build.

{noformat}
  <target name="external-javadocs" depends="props, compile-gemfire" 
unless="skip.external.jdocs">
    <mkdir dir="${docs.dir}"/>
    <mkdir dir="${docs.dir}/external"/>
    <javadoc additionalparam="-breakiterator -Xwerror -XDignore.symbol.file"
             maxmemory="${max.memory}M"
             locale="en_US" author="false"
             encoding="UTF-8"
             docencoding="UTF-8"
             destdir="${docs.dir}/external" failonerror="true" nohelp="yes"
             overview="${src.dir}/external-overview.html" public="true"
             sourcepath="${src.dir}" splitindex="yes" use="yes" version="false"
             windowtitle="GemFire Java API Documentation">
      <classpath>
        <pathelement location="${classes.dir}"/>
        <pathelement location="${findbugs-annotations.jar}"/>
        <fileset dir="${hiddenlib.dir}">
          <include name="**/*.jar"/>
        </fileset>
        <fileset dir="${product.lib.dir}">
          <include name="**/*.jar"/>
        </fileset>
      </classpath>
      <link href="http://java.sun.com/javase/6/docs/api/";
            offline="true"
            packagelistLoc="${javadocs.api.dir}"/>

      <package name="com/gemstone/gemfire/**/"/>
      <excludepackage name="com/gemstone/gemfire/internal/**/"/>
      <excludepackage name="com/gemstone/gemfire/**/internal/**/"/>
      <excludepackage name="com/gemstone/gemfire/**/xml/**/"/>
      <excludepackage name="com/gemstone/gemfire/distributed/**/util/**/"/>

      <tag description="&lt;I&gt;Note: Early Access. Please consult GemStone 
technical support for assistance with this functionality.&lt;/I&gt;" 
name="early.Access" enabled="false"/>
      <doctitle>&lt;h1&gt;GemFire ${gemfire.version} Java API 
&lt;/h1&gt;</doctitle>
      <header>&lt;i&gt;GemFire ${gemfire.version}&lt;/i&gt;</header>
      <bottom>&lt;i&gt;Copyright &amp;copy; 1997-2015 Pivotal Software, Inc. 
All rights reserved.&lt;/i&gt;</bottom>
    </javadoc>
    <!-- Copy files referenced by javadocs -->
    <copy todir="${docs.dir}/external">
      <fileset dir="${src.dir}">
        <include name="com/gemstone/gemfire/**/*.gif"/>
        <exclude name="com/gemstone/gemfire/**/internal/**"/>
      </fileset>
    </copy>

    <!-- Generate the HTML description of the JMX MBeans -->
    <property name="xmlFile"
              
value="${src.dir}/com/gemstone/gemfire/admin/jmx/mbeans-descriptors.xml"/>
    <property name="htmlDir"
              
value="${docs.dir}/external/com/gemstone/gemfire/admin/jmx/doc-files"/>
    <mkdir dir="${htmlDir}"/>
    <property name="htmlFile" value="${htmlDir}/mbeans-descriptions.html"/>
    <java classname="com.gemstone.gemfire.admin.jmx.internal.GenerateMBeanHTML"
          failonerror="true" fork="true">
      <classpath>
        <pathelement path="${classes.dir}"/>
        <pathelement location="${log4j-api.jar}"/>
        <pathelement location="${log4j-core.jar}"/>
      </classpath>
      <arg value="${xmlFile}"/>
      <arg value="${htmlFile}"/>
    </java>
    <echo message="Sweeping ${docs.dir}/external for internal references..."
          level="info"/>
    <checkjavadoc dir="${docs.dir}/external" debug="false">
      <docFiles dir="${docs.dir}/external">
        <exclude name="**/overview-tree.html"/>
        <exclude 
name="com/gemstone/gemfire/admin/jmx/doc-files/mbeans-descriptions.html"/>
        <exclude name="**/*.fig"/>
      </docFiles>
    </checkjavadoc>
  </target>



{noformat}



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)