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

[ASF subversion and git services (JIRA)]

    [ 
https://issues.apache.org/jira/browse/GEODE-572?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15129125#comment-15129125
 ] 

ASF subversion and git services commented on GEODE-572:
-------------------------------------------------------

Commit 01c9337ba7a8f12623652ba149c17b43fccc52d4 in incubator-geode's branch 
refs/heads/develop from [~upthewaterspout]
[ https://git-wip-us.apache.org/repos/asf?p=incubator-geode.git;h=01c9337 ]

GEODE-572: Generate public javadocs

Adding a task to generate javadocs for the public API as part of the
assembly project. The javadocs are now included in the binary
distribution in a folder called javadocs.


> 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)