License and Usage Terms of generated API documentation (original) (raw)

Volker Simonis volker.simonis at gmail.com
Thu May 3 12:16:11 UTC 2018

On Thu, May 3, 2018 at 12:21 PM, Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com> wrote:

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/javase-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: JAVADOCBASEURL := http://www.oracle.com/pls/topic/lookup?ctx=javase10&id=homepage BUGSUBMITURL := http://bugreport.java.com/bugreport/ COPYRIGHTURL := {@docroot}/../legal/copyright.html LICENSEURL := http://www.oracle.com/technetwork/java/javase/terms/license/java10speclicense.html REDISTRIBUTIONURL := http://www.oracle.com/technetwork/java/redist-137594.html "JAVADOCBASEURL" 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. "BUGSUBMITURL" should use the value of the already existing "--with-vendor-bug-url" if that was set at configure time. "COPYRIGHTURL" 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. "LICENSEURL" and "REDISTRIBUTIONURL" 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. 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.

Thanks for confirming this. That was my impression as well :)

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.

The JAVADOC_BASE_URL is the minor issue here and I agree that it would be not easy to create a community driven documentation of the same or at least similar quality as we have today from Oracle. Nevertheless I don't see why we shouldn't be able to make this URL configurable at configure time.

The main issue are the two links to "LICENSE_URL" and "REDISTRIBUTION_URL" which clearly refer to the API-docs published by Oracle. I just want to be able to publish these API-docs myself without having to refer to these restrictive licenses. The change itself, to make these URLs configurable at configure time, would be trivial (and again, I'm not against leaving the default "as-is" if this is important for you).

/Magnus

More information about the jdk-dev mailing list