ModeShape/modeshape — pull request #493 by rhauch (2012-08-23 16:11:03+00:00)
Title: MODE-1607 Fixed the JavaDoc generation errors due to 'provided' dependencies

After a lot of trial and error (and hangwringing), the easiest solution is to forcibly include the `provided` dependencies with a scope of `compile` in the `assembly` profile in the `modeshape-distribution/pom.xml` file.

Note that we are (and have been for quite some time) building our JavaDoc in one pass, rather than using aggregate JavaDocs for each module. The reason is that we only want to build the JavaDoc during assembly builds, and so the aggregate JavaDoc approach results in the JavaDoc assembly running the entire build as a fork (to build all of the modules _with_ JavaDoc); this means that a full assembly build would build all modules at least twice. This would make the builds significantly longer, and the Mead productization build process is not able to even handle such circular builds.

However, if we build the JavaDoc in one pass, then we simply have to have the `modeshape-distribution` module depend on all of the other modules for which we want to build JavaDoc and put into the assemblies (e.g., the distribution, source, and AS7 kit ZIP files). Normally this works great. But this fails as soon as we have 'provided' dependencies that our code references (since the dependencies will be available in the runtime environment); see [MJAVADOC-340](http://jira.codehaus.org/browse/MJAVADOC-340).

The solution that works is simply to include the normally `provided` dependencies in the dependencies list for the `assembly` profile.

Note that several other changes were made to the profile's definition to clean up the JavaDoc plugin configuration.

This pull-request also includes a few other changes to clean up JavaDoc comments and remove compiler warnings.