[all] multi-module project aggregate javadoc

[Alex Herbert <al...@gmail.com>]

Currently the multi-module projects RNG, Math, Numbers, and Geometry
create a site that has the javadocs spread through the various site
modules. However, in each project the modules are possible to use
altogether. So it would be useful to have an aggregate javadoc
somewhere on their sites.

Note this is in contrast to VFS where there is a link on the site at
the top level to the javadoc for the core vfs2 module that contains
the API. I believe the other modules are implementations of the API
and so the concept of an aggregate API is not applicable.

I have updated RNG to allow the docs module (previously used for
coverage reporting) to be included in the site. This generates an
aggregate javadoc report. The complete RNG API can then be viewed from
the docs module. The module is currently included via a profile:

> mvn clean package site -Pdocs site:stage
> open target/staging/commons-rng-docs/index.html

Or to view the module only:

> cd commons-rng-docs
> mvn site
> open target/site/index.html

A link to the aggregate javadoc can be added to the top level site
page; this requires the docs module to be included in the reactor to
avoid a dead link from the top level site descriptor (site.xml).

I suggest changing the docs module from optional to be included in the
reactor. Currently the 'mvn install' command takes around 6-8 seconds
to execute in the module as most of the standard build plugins are
disabled. So this has a low impact on total build time. This would
allow a site build to always assume the module is present and so add a
link at the top level site to the aggregate javadoc.

I can make a similar change to the other multi-module projects.

Alex

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [all] multi-module project aggregate javadoc

[Gary Gregory <ga...@gmail.com>]

I like the idea of an aggregate Javadoc, even for VFS :-) You never
know that something is documented until you see it!

Gary

On Tue, Oct 25, 2022 at 6:36 AM Alex Herbert <al...@gmail.com> wrote:
>
> Currently the multi-module projects RNG, Math, Numbers, and Geometry
> create a site that has the javadocs spread through the various site
> modules. However, in each project the modules are possible to use
> altogether. So it would be useful to have an aggregate javadoc
> somewhere on their sites.
>
> Note this is in contrast to VFS where there is a link on the site at
> the top level to the javadoc for the core vfs2 module that contains
> the API. I believe the other modules are implementations of the API
> and so the concept of an aggregate API is not applicable.
>
> I have updated RNG to allow the docs module (previously used for
> coverage reporting) to be included in the site. This generates an
> aggregate javadoc report. The complete RNG API can then be viewed from
> the docs module. The module is currently included via a profile:
>
> > mvn clean package site -Pdocs site:stage
> > open target/staging/commons-rng-docs/index.html
>
> Or to view the module only:
>
> > cd commons-rng-docs
> > mvn site
> > open target/site/index.html
>
> A link to the aggregate javadoc can be added to the top level site
> page; this requires the docs module to be included in the reactor to
> avoid a dead link from the top level site descriptor (site.xml).
>
> I suggest changing the docs module from optional to be included in the
> reactor. Currently the 'mvn install' command takes around 6-8 seconds
> to execute in the module as most of the standard build plugins are
> disabled. So this has a low impact on total build time. This would
> allow a site build to always assume the module is present and so add a
> link at the top level site to the aggregate javadoc.
>
> I can make a similar change to the other multi-module projects.
>
> Alex
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org