I agree that this issue should be addressed. However, is this something that needs to be done for this release, especially considering that this is a long-standing issue and the documentation in question is accessible in other locations?
Regards, Matt J On Tue, Aug 17, 2021 at 10:47 AM Alex Herbert <[email protected]> wrote: > > On Tue, 17 Aug 2021 at 13:18, Alex Herbert <[email protected]> wrote: > > > > > > > On Tue, 17 Aug 2021, 12:43 Gilles Sadowski, <[email protected]> wrote: > > > >> Hello. > >> > >> Le mar. 17 août 2021 à 11:58, Alex Herbert <[email protected]> a > >> écrit : > >> > > >> > Hi, > >> > > >> > I am sorry to report another issue. This is a long running one that has > >> > previously been unnoticed in releases. > >> > > >> > Looking inside the binary distributions I believe that the intention is > >> to > >> > provide documentation along with the binary jars. > >> > > >> > On a single module project such as lang this is provided as the javadoc > >> > directory. > >> > > >> > In our released multi-module projects (rng, numbers) this has been > >> provided > >> > as the site directory. However this is not actually packaging the > >> javadocs. > >> > >> Is there something wrong with (e.g. for [RNG] v1.3): > >> > >> https://repo1.maven.org/maven2/org/apache/commons/commons-rng-simple/1.3/commons-rng-simple-1.3-javadoc.jar > >> ? > >> > > > > The jars released to maven are ok. > > > > I am discussing the binary release that you download. The one that ends > > with .tar.gz or .zip. > > > > If you obtain it and unpack it there are all the package jar files and > > then a directory inside called docs. It is what should be in there that I > > am discussing. > > > > Currently it contains part of the site. I think it should contain the > > javadoc for all the binary jars. This is what is done for a single module > > release such as Lang. > > > > Is there a specification of what should be in a binary release? For example: > > commons-rng-1.3-bin.tar.gz > > This is 13M. If unpacked it is 44M. It has jars for the class files, the > source and the javadoc. Then it has part of the site which is 33M when > unpacked. > > If the intention is to include the javadoc then this can be obtained by > extracting the javadoc jar files. So including the javadoc as an additional > folder is duplicating information. > > In the case of commons-lang it contains jars as above but also the jars for > the test source and classes: > > CONTRIBUTING.md > > LICENSE.txt > > NOTICE.txt > > README.md > > RELEASE-NOTES.txt > > apidocs/ > > commons-lang3-3.12.0-javadoc.jar > > commons-lang3-3.12.0-sources.jar > > commons-lang3-3.12.0-test-sources.jar > > commons-lang3-3.12.0-tests.jar > > commons-lang3-3.12.0.jar > > The apidocs directory is the output of the javadoc command. If I extract > the commons-lang3-3.12.0-javadoc.jar then I get the same folder with a few > differences: > > diff apidocs/ tmp/ > > Only in tmp/: META-INF > > Common subdirectories: apidocs/org and tmp/org > > Only in apidocs/: src-html > > So including the apidocs directory seems to be wasteful duplication. > > Perhaps we should either: > > - include the user guide in the binary release > - not include anything other than the jar files > > Including part of the site is not helpful as it is incomplete and cannot be > browsed. Including a javadocs directory is duplication. But for a > multi-module project it can be created as an aggregate javadoc for the > entire release. This has some value if it is not included anywhere else > (i.e. as another jar in the binary archive). > > Alex --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
