License and Usage Terms of generated API documentation

Magnus Ihse Bursie magnus.ihse.bursie at oracle.com
Thu May 3 10:21:52 UTC 2018


On 2018-05-02 17:03, Volker Simonis wrote:
> Hi,
>
> we currently build OpenJDK and make it available from various sources
> (e.g. GitHub, apt-get server, DockerHub). We also build the API
> documentation (i.e. JavaDoc) and would like to make it available from
> our project page as well. However the default API doc produced by the
> build looks as follows:
>
> http://cr.openjdk.java.net/~simonis/webrevs/2018/jdk10-api-doc/overview-summary.html
>
> Especially the footer seems to be weired and only valid for the API
> doc hosted by Oracle itself. It reads as follows:
>
> Use is subject to "license terms" and the "documentation redistribution policy".
>
> "license terms" links to
> http://www.oracle.com/technetwork/java/javase/terms/license/java10speclicense.html
> which redirects to
> http://download.oracle.com/otndocs/jcp/java_se-10-final-spec/license.html
>
> "documentation redistribution policy" links to
> http://www.oracle.com/technetwork/java/redist-137594.html
>
> Especially the "documentation redistribution policy" is very strict. It states:
>
> "The Java SE API Specification is not redistributable."
>
> This is a very strong statement. While it may be fine for the API
> documentation hosted by Oracle (under
> https://docs.oracle.com/javase/10/docs/api/overview-summary.html) I
> doubt this can be valid for the OpenJDK API documentation which was
> produced exclusively from GPLv2 licensed sources (actually even GPLv2
> plus Classpath Exception). From my understanding the whole HTML tree
> generated by "make docs-image" should be by default licensed under
> GPLv2 as well.
>
> I would therefore like to propose to make the following variables from
> "make/Docs.gmk" configurable with corresponding configure flags:
>
> JAVADOC_BASE_URL :=
> http://www.oracle.com/pls/topic/lookup?ctx=javase10&id=homepage
> BUG_SUBMIT_URL := http://bugreport.java.com/bugreport/
> COPYRIGHT_URL := {@docroot}/../legal/copyright.html
> LICENSE_URL := http://www.oracle.com/technetwork/java/javase/terms/license/java10speclicense.html
> REDISTRIBUTION_URL := http://www.oracle.com/technetwork/java/redist-137594.html
>
> "JAVADOC_BASE_URL" should by default point to an OpenJDK site
> (although I'm not sure which one will be best suited). It seems
> strange that the default documentation generated from an OpenSource
> project like OpenJDK points to some Oracle-proprietary documentation.
>
> "BUG_SUBMIT_URL" should use the value of the already existing
> "--with-vendor-bug-url" if that was set at configure time.
>
> "COPYRIGHT_URL" currently points to "copyright.html" which doesn't
> exist neither in the OpenJDK sources nor in the generated images. Not
> sure what would be a useful default value here. Maybe just leave it
> empty? "Copyright © 1993, 2018, Oracle.." already seems
> self-explanatory and clear enough.
>
> "LICENSE_URL" and "REDISTRIBUTION_URL" should both by default point to
> the GPLv2+CPE LICENSE file and this LICENSE file should be copied into
> the API doc HTML tree (much like it is copied into the various
> subdirectories of the "legel/" directory of an OpenJDK image)
>
> I can open an issue for this topic and propose an implementation if
> there's consensus on this topic.
>
> Thank you and best regards,
> Volker
Since you added build-dev, I'll chip in some of my cents.

The code in the make file has been around like Forever<tm>. The current 
implementation is just what has been ported between frameworks and 
source control systems and updated for changes in release version and 
URL schemes.

I agree that is odd that the Oracle URL is hard-coded. On the other 
hand, there is no common place where generated OpenJDK documents are 
published. (The Oracle site technically speaking documents the Java 
Platform API, not the OpenJDK, even if any actual difference is minimal 
to non-existant wrt docs.)

It would make sense to me to have a OpenJDK-based documentation driven 
by the community. I'm guessing it's no easy thing to create this, 
though. A lot of links on the interwebz are pointing to the docs at 
docs.oracle.com, and it would probably be quite messy if the same (or 
even worse, almost the same) documentation were published both at 
docs.oracle.com and java.net. Also, the question arises as to who should 
do the hosting, and how.

So it's definitely a community issue to resolve, and one in which 
Oracle's legacy is important to take into consideration.

Until a consensus of a better solution for hosting the generated 
documentation is reached, I'd like to avoid changing the build code. 
That will just open for an uneccessary split in what constitutes the 
proper documentation URL.

/Magnus



More information about the jdk-dev mailing list