If a project has more than one javadoc_library rule in it, one may end up sharing the other's contents to some degree, if --spawn_strategy=local is set, such as in the .bazelrc file.
As long as each invocation of the rule is run in series, there will be no obvious difference from viewing the HTML results - the index.html etc will only point to the expected classes. In theory there could be obvious bugs if the rules are run in parallel, but I haven't seen this occur. The bug is obvious though when inspecting the contents of the javadoc jar.
Example BUILD file:
javadoc_library(
name = "foo",
srcs = ["Foo.java"],
)
javadoc_library(
name = "bar",
srcs = ["Bar.java"],
)
Where a trivial java file exists for each of these two classes. You would expect to find that each jar contains only the class it references, but instead one will contain both. This will happen even if the rules are declared in different BUILD files in different directories, but different invocations of bazel seem to not share contents.
I have also seen that if the tmp/ directory already exists in the root directory of the project, its contents can be merged into the output javadoc jar, but I can't consistently reproduce that.
I believe this is a bug in the javadoc_library rule, it is not correctly declaring the output it creates and keeping it as "hermetic" as it should. Presently, all output is written to a tmp/ directory, which happens to be in the root of the project (regardless of where bazel is invoked from, or where the rule itself is declared):
Instead, this directory should probably be in the same directory as the output. My understanding of bazel is that this idea could look something like:
tmp = ctx.actions.declare_directory("%s_javadoc" % ctx.attr.name)
javadoc_command = [
java_home + "/bin/javadoc",
"-use",
"-encoding UTF8",
"-classpath",
":".join([jar.path for jar in classpath]),
"-notimestamp",
"-d %s" % tmp.path, # point to the newly created direc
"-Xdoclint:-missing",
"-quiet",
]
In turn, the later jar command would need to consume this new file:
If a project has more than one
javadoc_libraryrule in it, one may end up sharing the other's contents to some degree, if--spawn_strategy=localis set, such as in the.bazelrcfile.As long as each invocation of the rule is run in series, there will be no obvious difference from viewing the HTML results - the index.html etc will only point to the expected classes. In theory there could be obvious bugs if the rules are run in parallel, but I haven't seen this occur. The bug is obvious though when inspecting the contents of the javadoc jar.
Example BUILD file:
Where a trivial java file exists for each of these two classes. You would expect to find that each jar contains only the class it references, but instead one will contain both. This will happen even if the rules are declared in different BUILD files in different directories, but different invocations of bazel seem to not share contents.
I have also seen that if the
tmp/directory already exists in the root directory of the project, its contents can be merged into the output javadoc jar, but I can't consistently reproduce that.I believe this is a bug in the javadoc_library rule, it is not correctly declaring the output it creates and keeping it as "hermetic" as it should. Presently, all output is written to a
tmp/directory, which happens to be in the root of the project (regardless of wherebazelis invoked from, or where the rule itself is declared):https://github.com/google/bazel-common/blob/bf8e5ef95b118d1716b0cb4982cf15b6ed1c896f/tools/javadoc/javadoc.bzl#L42
Instead, this directory should probably be in the same directory as the output. My understanding of bazel is that this idea could look something like:
In turn, the later jar command would need to consume this new file:
and the action declare this directory as an output: