Let one package-info stand per package, and aggregate Javadoc before the merge

[vharseko]

What broke

mvn javadoc:aggregate in deploy.yml has failed on every Package/Deploy run since #734 turned on failOnWarnings:

[ERROR] Failed to execute goal maven-javadoc-plugin:3.12.0:aggregate (default-cli)
on project opendj-parent:
An error has occurred in Javadoc report generation: Project contains Javadoc Warnings
5 warnings

All five are the same warning — a package-info.java file has already been seen for package … — because five packages are each declared by a package-info.java in two modules at once:

package	modules
org.opends.server.api	opendj-legacy + opendj-server-legacy
org.opends.server.schema	same
org.opends.server.backends.jeb	same
org.opends.server.replication.plugin	same
org.forgerock.opendj.examples	opendj-ldap-sdk-examples + opendj-embedded-server-examples

Per-module javadoc:jar never sees this — each module only reads its own sources. Only the root aggregate feeds every module's source roots to one javadoc run, and there the same package arrives twice.

The <failOnWarnings>true</failOnWarnings> sits at plugin level in the parent pom, so it applies to the CLI default-cli execution too, not just the bound attach-javadocs one.

Why nobody noticed

The Build Javadoc step carries continue-on-error: true, so the job stayed green and javadoc still emitted its ~5900 files before the plugin complained — the doc site kept publishing. Only a red annotation on the step marked it. Same annotation on runs 32478804616, 31605387204 and 31206191853.

And build.yml could not catch it: it runs mvn verify, and javadoc:aggregate appears in no workflow but deploy.yml.

The change

Drop the duplicate package-info.java. Only these five files were duplicated — no classes overlap between the module pairs. In every case the surviving copy is the richer one (full text plus @PublicAPI); the one sentence that lived only in the deleted copy is folded into the survivor:

• opendj-server-legacy/…/backends/jeb/package-info.java gains "These classes are here just to support upgrade and are deprecated."
• opendj-ldap-sdk-examples/…/examples/package-info.java now also names the Embedded Server API.

All four opendj-legacy packages keep real classes (42 in schema, 1–2 in the rest) — only the doc-only stubs go.

Gate the aggregate on build.yml. The javadoc:aggregate goal is appended to the existing mvn … verify invocation on the ubuntu / Java 11 cell — the platform and JDK deploy.yml aggregates with. deploy.yml is left as it is: the pre-merge gate is the right place for this to fail.

Verification

mvn javadoc:aggregate with the pom's own settings (doclint=all,-missing, failOnWarnings=true) — BUILD SUCCESS, 5884 HTML files, zero already been seen warnings. With failOnWarnings active, a green run is itself the proof that no javadoc warning is left.