[icedtea-web] RFC: Add documentation support
Dr Andrew John Hughes
ahughes at redhat.com
Fri Nov 26 07:41:30 PST 2010
On 10:20 Fri 26 Nov , Deepak Bhole wrote:
> * Dr Andrew John Hughes <ahughes at redhat.com> [2010-11-26 10:13]:
> > On 15:10 Fri 26 Nov , Dr Andrew John Hughes wrote:
> > > This adds API docs for the NetX and plugin packages, as promised
> > > yesterday. We did do this before (it lurked deep in a patch to
> > > the OpenJDK build) but I've expanded it to also cover the NetX
> > > classes (which are quite well-documented) and the plugin.
> > >
> > > I haven't covered this in the patch, but we should also be installing
> > > the architecture documentation provided by Deepak.
> > >
> > > 2010-11-25 Andrew John Hughes <ahughes at redhat.com>
> > >
> > > * Makefile.am:
> > > (JDK_UPDATE_VERSION): Document.
> > > (NETX_PKGS): NetX packages for documentation.
> > > (PLUGIN_PKGS): Same for the plugin.
> > > (JAVADOC_OPTS): Common options passed to javadoc.
> > > (JAVADOC_MEM_OPTS): Memory options passed to JVM
> > > if possible (taken from the previous OpenJDK build).
> > > (all-local): Depend on docs.stamp.
> > > (clean-local): Add clean-docs.
> > > (.PHONY): Add clean-docs, clean-plugin-docs, clean-netx-docs.
> > > (install-exec-local): Install the documentation if enabled.
> > > (docs): Meta-dependency for netx-docs and plugin-docs.
> > > (clean-docs): Likewise but for clean targets.
> > > (netx-docs): Build documentation for the NetX API.
> > > (clean-netx-docs): Remove the NetX docs.
> > > (plugin-docs): Build documentation for the plugin API.
> > > (clean-plugin-docs): Likewise.
> > > (bootstrap-directory): Link to javadoc binary.
> > > * acinclude.m4:
> > > (IT_FIND_JAVADOC): Find a javadoc binary, first checking
> > > user input, then the JDK and the path for 'javadoc' and
> > > 'gjdoc'. Also sets JAVADOC_SUPPORTS_J_OPTIONS if it does.
> > > * configure.ac:
> > > Call IT_FIND_JAVADOC.
> > >
> > > Ok?
> > > --
> > > Andrew :)
> > >
> > > Free Java Software Engineer
> > > Red Hat, Inc. (http://www.redhat.com)
> > >
> > > Support Free Java!
> > > Contribute to GNU Classpath and the OpenJDK
> > > http://www.gnu.org/software/classpath
> > > http://openjdk.java.net
> > > PGP Key: 94EFD9D8 (http://subkeys.pgp.net)
> > > Fingerprint = F8EF F1EA 401E 2E60 15FA 7927 142C 2591 94EF D9D8
> >
> > Attaching a patch would be a good idea...
> >
>
> Just a minor thing I noticed (missed it last time because I confused it
> with plugin docs :/) .. the docs/ dir is left behind after a make clean.
> Stamps are removed correctly though.
>
> So it just needs an rmdir in clean-docs
>
Yeah got your note on this on IRC.
I'm going to do a make distcheck and cover all such issues with one patch.
> Cheers,
> Deepak
>
> > Seems Deepak already approved it anyway, and there are no additional changes.
> > --
> > Andrew :)
> >
> > Free Java Software Engineer
> > Red Hat, Inc. (http://www.redhat.com)
> >
> > Support Free Java!
> > Contribute to GNU Classpath and the OpenJDK
> > http://www.gnu.org/software/classpath
> > http://openjdk.java.net
> > PGP Key: 94EFD9D8 (http://subkeys.pgp.net)
> > Fingerprint = F8EF F1EA 401E 2E60 15FA 7927 142C 2591 94EF D9D8
>
> > diff -r dcd3d1728ff4 Makefile.am
> > --- a/Makefile.am Wed Nov 24 15:47:50 2010 -0500
> > +++ b/Makefile.am Thu Nov 25 17:35:45 2010 +0000
> > @@ -17,12 +17,20 @@
> > IT_CLASS_TARGET_VERSION=6
> > IT_JAVACFLAGS=$(IT_JAVAC_SETTINGS) -source $(IT_LANGUAGE_SOURCE_VERSION) -target $(IT_CLASS_TARGET_VERSION)
> >
> > +# Fake update version to shut up the plugin detector hosted by Oracle.
> > +# If Oracle ever release a JDK update greater than 50, this needs to be increased.
> > JDK_UPDATE_VERSION=50
> >
> > # Sources list
> >
> > PLUGIN_TEST_SRCS = $(abs_top_srcdir)/plugin/tests/LiveConnect/*.java
> >
> > +NETX_PKGS = javax.jnlp net.sourceforge.nanoxml net.sourceforge.jnlp \
> > + net.sourceforge.jnlp.cache net.sourceforge.jnlp.event \
> > + net.sourceforge.jnlp.security net.sourceforge.jnlp.security.viewer \
> > + net.sourceforge.jnlp.services net.sourceforge.jnlp.tools \
> > + net.sourceforge.jnlp.util
> > +
> > # Conditional defintions
> > if ENABLE_PLUGIN
> > ICEDTEAPLUGIN_CLEAN = clean-IcedTeaPlugin
> > @@ -32,6 +40,7 @@
> > LIVECONNECT_SRCS = $(PLUGIN_SRCDIR)/java
> > ICEDTEAPLUGIN_TARGET = $(PLUGIN_DIR)/IcedTeaPlugin.so stamps/liveconnect-dist.stamp \
> > $(PLUGIN_DIR)/launcher/pluginappletviewer
> > +PLUGIN_PKGS = sun.applet netscape.security netscape.javascript
> > endif
> >
> > if CP_SUPPORTS_REFLINK
> > @@ -51,6 +60,14 @@
> > ICEDTEA_PKG = $(EMPTY) (${PKGVERSION})
> > endif
> >
> > +if ENABLE_DOCS
> > +JAVADOC_OPTS=-use -keywords -encoding UTF-8 -splitIndex \
> > + -bottom '<font size="-1"> <a href="http://icedtea.classpath.org/bugzilla">Submit a bug or feature</a></font>'
> > +if JAVADOC_SUPPORTS_J_OPTIONS
> > +JAVADOC_MEM_OPTS=-J-Xmx1024m -J-Xms128m -J-XX:PermSize=32m -J-XX:MaxPermSize=160m
> > +endif
> > +endif
> > +
> > # Launcher
> >
> > LAUNCHER_SRCDIR = $(abs_top_srcdir)/launcher
> > @@ -72,13 +89,13 @@
> > # =================
> >
> > all-local: stamps/netx-dist.stamp extra-lib/about.jar stamps/plugin.stamp $(NETX_DIR)/launcher/javaws \
> > - javaws.desktop
> > + javaws.desktop stamps/docs.stamp
> >
> > clean-local: clean-netx clean-plugin clean-liveconnect clean-extra clean-bootstrap-directory \
> > - clean-native-ecj clean-desktop-files
> > + clean-native-ecj clean-desktop-files clean-docs
> >
> > .PHONY: clean-IcedTeaPlugin clean-add-netx clean-add-netx-debug clean-add-plugin clean-add-plugin-debug \
> > - clean-bootstrap-directory clean-native-ecj clean-desktop-files
> > + clean-bootstrap-directory clean-native-ecj clean-desktop-files clean-netx-docs clean-docs clean-plugin-docs
> >
> > install-exec-local:
> > mkdir -p $(DESTDIR)$(bindir)
> > @@ -96,6 +113,13 @@
> > mkdir -p $(DESTDIR)$(prefix)/man/man1
> > cp $(NETX_SRCDIR)/javaws.1 $(DESTDIR)$(prefix)/man/man1
> > cp $(NETX_RESOURCE_DIR)/about.jnlp $(DESTDIR)$(prefix)/jre/lib
> > +if ENABLE_DOCS
> > + mkdir -p $(DESTDIR)$(htmldir)
> > + cp -pPRf ${abs_top_builddir}/docs/netx $(DESTDIR)$(htmldir)
> > +if ENABLE_PLUGIN
> > + cp -pPRf ${abs_top_builddir}/docs/plugin $(DESTDIR)$(htmldir)
> > +endif
> > +endif
> >
> > uninstall-local:
> > rm -f $(DESTDIR)$(prefix)/jre/lib/$(INSTALL_ARCH_DIR)/IcedTeaPlugin.so
> > @@ -284,6 +308,48 @@
> > javaws.desktop: javaws.desktop.in
> > sed "s#PATH_TO_JAVAWS#$(DESTDIR)$(bindir)/javaws#" < $(srcdir)/javaws.desktop.in > javaws.desktop
> >
> > +# documentation
> > +
> > +stamps/docs.stamp: stamps/netx-docs.stamp stamps/plugin-docs.stamp
> > + touch stamps/docs.stamp
> > +
> > +clean-docs: clean-netx-docs clean-plugin-docs
> > + rm -f stamps/docs.stamp
> > +
> > +stamps/netx-docs.stamp: stamps/bootstrap-directory.stamp
> > +if ENABLE_DOCS
> > + $(BOOT_DIR)/bin/javadoc $(JAVADOC_MEM_OPTS) $(JAVADOC_OPTS) \
> > + -d ${abs_top_builddir}/docs/netx -sourcepath $(NETX_SRCDIR) \
> > + -doctitle 'IcedTea-Web: NetX API Specification' \
> > + -windowtitle 'IcedTea-Web: NetX ' \
> > + -header '<strong>IcedTea-Web<br/>NetX</strong>' \
> > + $(NETX_PKGS)
> > +endif
> > + mkdir -p stamps
> > + touch stamps/netx-docs.stamp
> > +
> > +clean-netx-docs:
> > + rm -rf ${abs_top_builddir}/docs/netx
> > + rm -f stamps/netx-docs.stamp
> > +
> > +stamps/plugin-docs.stamp: stamps/bootstrap-directory.stamp
> > +if ENABLE_DOCS
> > +if ENABLE_PLUGIN
> > + $(BOOT_DIR)/bin/javadoc $(JAVADOC_MEM_OPTS) $(JAVADOC_OPTS) \
> > + -d ${abs_top_builddir}/docs/plugin -sourcepath $(NETX_SRCDIR):$(LIVECONNECT_SRCS) \
> > + -doctitle 'IcedTea-Web: Plugin API Specification' \
> > + -windowtitle 'IcedTea-Web: Plugin ' \
> > + -header '<strong>IcedTea-Web<br/>Plugin</strong>' \
> > + $(PLUGIN_PKGS)
> > +endif
> > +endif
> > + mkdir -p stamps
> > + touch stamps/plugin-docs.stamp
> > +
> > +clean-plugin-docs:
> > + rm -rf ${abs_top_builddir}/docs/plugin
> > + rm -f stamps/plugin-docs.stamp
> > +
> > # plugin tests
> >
> > if ENABLE_PLUGIN
> > @@ -322,6 +388,7 @@
> > mkdir -p $(BOOT_DIR)/bin stamps/
> > ln -sf $(JAR) $(BOOT_DIR)/bin/jar
> > ln -sf $(abs_top_builddir)/javac $(BOOT_DIR)/bin/javac
> > + ln -sf $(JAVADOC) $(BOOT_DIR)/bin/javadoc
> > mkdir -p $(BOOT_DIR)/jre/lib && \
> > ln -s $(SYSTEM_JDK_DIR)/jre/lib/rt.jar $(BOOT_DIR)/jre/lib && \
> > if [ -e $(SYSTEM_JDK_DIR)/jre/lib/jsse.jar ] ; then \
> > diff -r dcd3d1728ff4 acinclude.m4
> > --- a/acinclude.m4 Wed Nov 24 15:47:50 2010 -0500
> > +++ b/acinclude.m4 Thu Nov 25 17:35:45 2010 +0000
> > @@ -543,3 +543,65 @@
> > AC_MSG_RESULT(${JAVA})
> > AC_SUBST(JAVA)
> > ])
> > +
> > +AC_DEFUN([IT_FIND_JAVADOC],
> > +[
> > + AC_REQUIRE([IT_CHECK_FOR_JDK])
> > + AC_MSG_CHECKING([for javadoc])
> > + AC_ARG_WITH([javadoc],
> > + [AS_HELP_STRING(--with-javadoc,specify location of Java documentation tool (javadoc))],
> > + [
> > + JAVADOC="${withval}"
> > + ],
> > + [
> > + JAVADOC=${SYSTEM_JDK_DIR}/bin/javadoc
> > + ])
> > + if ! test -f "${JAVADOC}"; then
> > + AC_PATH_PROG(JAVADOC, "${JAVADOC}")
> > + fi
> > + if test -z "${JAVADOC}"; then
> > + AC_PATH_PROG(JAVADOC, "javadoc")
> > + fi
> > + if test -z "${JAVADOC}"; then
> > + AC_PATH_PROG(JAVADOC, "gjdoc")
> > + fi
> > + if test -z "${JAVADOC}" && test "x$ENABLE_DOCS" = "xyes"; then
> > + AC_MSG_ERROR("No Java documentation tool was found.")
> > + fi
> > + AC_MSG_RESULT(${JAVADOC})
> > + AC_MSG_CHECKING([whether javadoc supports -J options])
> > + CLASS=pkg/Test.java
> > + mkdir tmp.$$
> > + cd tmp.$$
> > + mkdir pkg
> > + cat << \EOF > $CLASS
> > +[/* [#]line __oline__ "configure" */
> > +package pkg;
> > +
> > +public class Test
> > +{
> > + /**
> > + * Does stuff.
> > + *
> > + *
> > + * @param args arguments from cli.
> > + */
> > + public static void main(String[] args)
> > + {
> > + System.out.println("Hello World!");
> > + }
> > +}
> > +]
> > +EOF
> > + if $JAVADOC -J-Xmx896m pkg >&AS_MESSAGE_LOG_FD 2>&1; then
> > + JAVADOC_KNOWS_J_OPTIONS=yes
> > + else
> > + JAVADOC_KNOWS_J_OPTIONS=no
> > + fi
> > + cd ..
> > + rm -rf tmp.$$
> > + AC_MSG_RESULT([${JAVADOC_KNOWS_J_OPTIONS}])
> > + AC_SUBST(JAVADOC)
> > + AC_SUBST(JAVADOC_KNOWS_J_OPTIONS)
> > + AM_CONDITIONAL([JAVADOC_SUPPORTS_J_OPTIONS], test x"${JAVADOC_KNOWS_J_OPTIONS}" = "xyes")
> > +])
> > diff -r dcd3d1728ff4 configure.ac
> > --- a/configure.ac Wed Nov 24 15:47:50 2010 -0500
> > +++ b/configure.ac Thu Nov 25 17:35:45 2010 +0000
> > @@ -32,6 +32,7 @@
> > FIND_JAVAC
> > FIND_JAR
> > FIND_ECJ_JAR
> > +IT_FIND_JAVADOC
> > AC_CONFIG_FILES([javac], [chmod +x javac])
> >
> > IT_GET_PKGVERSION
>
--
Andrew :)
Free Java Software Engineer
Red Hat, Inc. (http://www.redhat.com)
Support Free Java!
Contribute to GNU Classpath and the OpenJDK
http://www.gnu.org/software/classpath
http://openjdk.java.net
PGP Key: 94EFD9D8 (http://subkeys.pgp.net)
Fingerprint = F8EF F1EA 401E 2E60 15FA 7927 142C 2591 94EF D9D8
More information about the distro-pkg-dev
mailing list