You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@geode.apache.org by "Dan Smith (JIRA)" <ji...@apache.org> on 2016/02/02 23:01:39 UTC

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

     [ https://issues.apache.org/jira/browse/GEODE-572?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Dan Smith resolved GEODE-572.
-----------------------------
    Resolution: Fixed

> 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
>          Components: build, general, web-content
>            Reporter: Dan Smith
>            Assignee: 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)