Apple Extensions are not documented in Java 7 API Docs

[Andrew Hughes]

----- Original Message -----
> This may be totally off base but is there any reason *not* to change
> the OpenJDK build to include some javadoc generation for this
> additional API?
> 

I did a bit of digging... :-D

It already lists the packages in make/docs/NON_CORE_PKGS.gmk:

ifeq ($(PLATFORM), macosx)
APPLE_EXT_PKGS   = com.apple.concurrent   \
                   com.apple.eawt         \
                   com.apple.eawt.event   \
                   com.apple.eio
endif

but there is no rule in make/docs/Makefile to build them, nor is
src/macosx/classes listed in ALL_SOURCE_DIRS.

Something like the following:

diff --git a/make/docs/Makefile b/make/docs/Makefile
--- a/make/docs/Makefile
+++ b/make/docs/Makefile
@@ -86,6 +86,7 @@
                   $(GENSRCDIR) \
                   $(SHARE_SRC)/../solaris/classes \
 	          $(SHARE_SRC)/../windows/classes \
+		  $(SHARE_SRC)/../macosx/classes \
 		  $(SHARE_SRC)/doc/stub
 
 # List of directories that actually exist
@@ -1098,6 +1099,56 @@
 
 #############################################################
 #
+# appleextdocs
+#
+
+ALL_OTHER_TARGETS += appleextdocs
+
+APPLE_EXT_DOCDIR      := $(JRE_API_DOCSDIR)/apple
+APPLE_EXT2COREAPI     := ../../../$(JDKJRE2COREAPI)
+APPLE_EXT_DOCTITLE    := Apple Ext API
+APPLE_EXT_WINDOWTITLE := Apple Ext API
+APPLE_EXT_HEADER      := <strong>Apple Ext API</strong>
+APPLE_EXT_BOTTOM      := $(call CommonBottom,$(APPLE_EXT_FIRST_COPYRIGHT_YEAR))
+# APPLE_EXT_PKGS is located in NON_CORE_PKGS.gmk
+
+APPLE_EXT_INDEX_HTML    = $(APPLE_EXT_DOCDIR)/index.html
+APPLE_EXT_OPTIONS_FILE  = $(DOCSTMPDIR)/appleext.options
+APPLE_EXT_PACKAGES_FILE = $(DOCSTMPDIR)/appleext.packages
+
+appleextdocs: $(APPLE_EXT_INDEX_HTML)
+
+# Set relative location to core api document root
+$(APPLE_EXT_INDEX_HTML): GET2DOCSDIR=$(APPLE_EXT2COREAPI)/..
+
+# Run javadoc if the index file is out of date or missing
+$(APPLE_EXT_INDEX_HTML): $(APPLE_EXT_OPTIONS_FILE) $(APPLE_EXT_PACKAGES_FILE)
+	$(prep-javadoc)
+	$(call JavadocSummary,$(APPLE_EXT_OPTIONS_FILE),$(APPLE_EXT_PACKAGES_FILE))
+	$(JAVADOC_CMD) $(JAVADOC_VM_MEMORY_FLAGS) -d $(@D) \
+	  @$(APPLE_EXT_OPTIONS_FILE) @$(APPLE_EXT_PACKAGES_FILE)
+
+# Create file with javadoc options in it
+$(APPLE_EXT_OPTIONS_FILE):
+	$(prep-target)
+	@($(call OptionOnly,$(COMMON_JAVADOCFLAGS))			; \
+	  $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH))	; \
+	  $(call OptionPair,-encoding,ascii)				; \
+	  $(call OptionOnly,-nodeprecatedlist)				; \
+	  $(call OptionPair,-doctitle,$(APPLE_EXT_DOCTITLE))		; \
+	  $(call OptionPair,-windowtitle,$(APPLE_EXT_WINDOWTITLE) $(DRAFT_WINTITLE));\
+	  $(call OptionPair,-header,$(APPLE_EXT_HEADER)$(DRAFT_HEADER))	; \
+	  $(call OptionPair,-bottom,$(APPLE_EXT_BOTTOM)$(DRAFT_BOTTOM))	; \
+	  $(call OptionTrip,-linkoffline,$(APPLE_EXT2COREAPI),$(COREAPI_DOCSDIR)/); \
+        ) >> $@
+
+# Create a file with the package names in it
+$(APPLE_EXT_PACKAGES_FILE): $(DIRECTORY_CACHE) $(call PackageDependencies,$(APPLE_EXT_PKGS))
+	$(prep-target)
+	$(call PackageFilter,$(APPLE_EXT_PKGS))
+
+#############################################################
+#

allows the documentation to be built (rule just copied from the one above and
the names altered).

With the above patch, and a few additional modifications to build and find the MacOSX
classes on GNU/Linux, I was able to build the documentation for those classes.

Beware; javadoc prints out quite a few warnings!

> On Mon, Aug 13, 2012 at 9:02 AM, Paul Taylor <paul_t100 at fastmail.fm>
> wrote:
> > On 13/08/2012 15:40, Mario Torre wrote:
> >>
> >> 2012/8/13 Paul Taylor <paul_t100 at fastmail.fm>:
> >>
> >>> You really should aim to incorporate support for these features
> >>> (however
> >>> it
> >>> is done) because Apple is only addressing shortfalls in Java
> >>> Swing
> >>> because
> >>> of its Windows centric approach. Seeing that Apple have made
> >>> these
> >>> extensions available to the Oracle 7 build they must been keen
> >>> for you to
> >>> a
> >>> good job. It cannot be right to not document these features
> >>> because  they
> >>> are deprecated features that shouldnt be used in new projects,
> >>> they are
> >>> the
> >>> only way to create quality Apple applications at the moment.
> >>>
> >>> Paul
> >>
> >> Artem already provided you with a rationale why this is not going
> >> to be supported, which is particularly valid since the mac port
> >> project
> >> is part of the official OpenJDK repository.
> >>
> >> Note that the fact that is not an official library, doesn't mean
> >> it's
> >> not there. You can surely find a way to keep using those
> >> extensions,
> >> the Mac guys can even help you with that, but the standard word of
> >> warning that if you use this extensions your programs may break
> >> any
> >> time is to be expected.
> >>
> >> Cheers,
> >> Mario
> >
> > You seem to be missing the point bigtime here.
> >
> > Its not an official library, but it is shipped as part of the jdk,
> > Im not
> > downloading it from a 3rd party. So as it is being delivered why is
> > it not
> > documented ?
> >
> > Going forward surely it is a good thing for Java to be able to
> > support the
> > desktop on different oses as good as possible, why would you want
> > to break
> > this, do you develop OSX desktop applications yourself
> >
> > Paul
> 

-- 
Andrew :)

Free Java Software Engineer
Red Hat, Inc. (http://www.redhat.com)

PGP Key: 248BDC07 (https://keys.indymedia.org/)
Fingerprint = EC5A 1F5E C0AD 1D15 8F1F  8F91 3B96 A578 248B DC07