Fix javadoc for java11

[tomas-langer]

Javadoc fails with errors such as:

org.apache.maven.reporting.MavenReportException:
Exit code: 1 - javadoc: error - The code being documented uses modules but the packages defined in http://www.reactive-streams.org/reactive-streams-1.0.2-javadoc/ are in the unnamed module.

The documentation is actually generated.

For the time being, javadoc will not fail the build. This must be fixed before release.

[barchetta]

Is this related to:

https://bugs.openjdk.java.net/browse/JDK-8212233

if so, a fix might be getting backported to 11. Although the issues implies it was fixed in 11.0.3, but maybe I'm not reading it right.

[barchetta]

This has been addressed by #1386. The changes:

1. Adding/updating module-info files
2. Using the maven-javadoc-plugin aggregate goal (instead of the roll-our-own approach we had before). And running it as part of the site lifecycle. So there is no more "javadoc" module.
3. Upgrading to version 3.2.0 of maven-javadoc-plugin to build the aggregated javadoc. This currently requires us to build that plugin from source since it isn't released yet (but the source is tagged). Expecting a release any day now.
4. Commenting out cross reference links from the javadoc config (will need to fix this)
5. Also, the documentation is now built as part of the site lifecycle.

To build the aggregated javadocs you run:

mvn site -Dversion.plugin.javadoc=3.2.0 -DskipTests -Pjavadoc

It will generate the aggregated javadocs and the documentation in the top level target directory. This currently requires you to build version 3.2.0 of the maven-javadoc-plugin yourself (see etc/build.sh). We expect it to be released any day now so this is a short term hack.