Cannot specify srcjars as srcs for javadoc_library

[tbroyer]

In google/elemental2, most Java sources are actually generated by google/jsinterop-generator (jsinterop_generator rules), and I can't seem to generate javadoc for those using e.g. srcs = [":libcore-src.jar"]

Actually, it looks like srcs is only used to compute whether the rule is uptodate or needs to be re-run, and root_packages and exclude_packages are the real inputs to the javadoc command.

[tbroyer]

I hacked around this by moving the

  srcs = depset(transitive = [src.files for src in ctx.attr.srcs]).to_list()

line up to the beginning of _javadoc_library and adding

 + ":".join([src.path for src in srcs])

to the end of the -sourcepath.

That probably should filter the join to only keep paths that end in -src.jar and/or .srcjar, or something like that (or directly filter the srcs attribute somehow)

[ronshapiro]

Hmm, I didn't realize that javadoc will process source jars, that's cool.

What about adding a srcjars attribute to the rule?

[tbroyer]

Hmm, I didn't realize that javadoc will process source jars, that's cool.

The way you call javadoc here, you don't give it source files, but a pair of packages + source path (see https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html)

BTW, I haven't checked (because I haven't had the need), but apparently you pass the packages as a single colon-separated argument, rather than separate arguments, so specifying several values in root_packages might not work as expected.

What about adding a srcjars attribute to the rule?

SGTM

Still feels weird that srcs is not actually taken into account other than for up-to-date checks, and you actually have to filter your sources through root_packages and exclude_packages; doesn't really match how other Bazel rules work AFAICT. Should it be renamed to something else? At a minimum its documentation needs to be changed, as the source files are not processed (e.g. "source files, used solely to determine if the rule is up-to-date; all sources in the given packages will actually be processed")