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
