Javadoc Generation

[f3rdy]

I'm happily creating a java-project along with resolving maven-dependencies. I can build a java_library perfectly. I saw, that I might be able to run tests with java_test (not yet checked). But what about those issues:

• create javadoc package
• deploy the results to a maven repository.

Is there any convinient way to do this with bazel?

thanks, Fred

[ulfjack]

I'm not aware of a convenient way to do that right now. I think it should be possible to implement a javadoc generator with extra actions ( http://bazel.io/docs/build-encyclopedia.html#extra_action), but I've never actually tried.

On Fri, Sep 11, 2015 at 5:04 PM, Fred Thiele notifications@github.com wrote:

I'm happily creating a java-project along with resolving maven-dependencies. I can build a java_library perfectly. I saw, that I might be able to run tests with java_test (not yet checked). But what about those issues:

• create javadoc package
• deploy the results to a maven repository.

Is there any convinient way to do this with bazel?

thanks, Fred

— Reply to this email directly or view it on GitHub https://github.com/bazelbuild/bazel/issues/446.

[davidzchen]

There currently isn't a way to do that with Bazel, but I think it would be possible to write a Skylark rule that generates a javadoc package. I wrote a similar d_docs rule for generating docs for D projects and creating a zip file containing the docs.

A java_docs rule could do something similar and generate a javadoc package for Maven.

I am less sure about having Bazel deploy artifacts to Maven since it is a non-hermetic operation. Do we have plans to support deploying build artifacts given that we have a mobile-install command?

[f3rdy]

Thanks for your valuable answers so far. I guess either writing a rule or using extra_actions along with an action_listener could do the job. But it would just be fine, if there'd be a set of standard mechanism to build the most common java artifacts (java_binary, java_library, /java_source_pkg/, /java_javadoc_pkg/) right out of the box. I think, the deployment (publishing) of these artifacts to a maven repository might be an off-topic for bazel (while "publishing" is a fairly common issue for e.g. gradle dsl), but it should'nt. Anyway, I'm curious about additional things to be adressed, when one potentially wants to take blaze into a serious account for building (large) java projects. So what about versioning and releasing artifacts for instance? A common way to look at this in the java world is maven or even custom layouts with ivy publishing... I'm not so sure if these types of technologies would be just off-topic. Just some thoughts... Thanks.

[ulfjack]

I expect that we'll support deploying build artifacts eventually. We have roughly similar functionality internally as well. It's just too convenient to be able to do it with the same tool that also builds the stuff in the first place.

On Sat, Sep 12, 2015 at 7:00 AM, Fred Thiele notifications@github.com wrote:

Thanks for your valuable answers so far. I guess either writing a rule or using extra_actions along with an action_listener could do the job. But it would just be fine, if there'd be a set of standard mechanism to build the most common java artifacts (java_binary, java_library, /java_source_pkg/, /java_javadoc_pkg/) right out of the box. I think, the deployment (publishing) of these artifacts to a maven repository might be an off-topic for bazel (while "publishing" is a fairly common issue for e.g. gradle dsl), but it should'nt. Anyway, I'm curious about additional things to be adressed, when one potentially wants to take blaze into a serious account for building (large) java projects. So what about versioning and releasing artifacts for instance? A common way to look at this in the java world is maven or even custom layouts with ivy publishing... I'm not so sure if these types of technologies would be just off-topic. Just some thoughts... Thanks.

— Reply to this email directly or view it on GitHub https://github.com/bazelbuild/bazel/issues/446#issuecomment-139721814.

[f3rdy]

@ulfjack I like your sense of humor.

[hanwen]

I was asked about javadoc for Bazel support in Gerrit. The current Buck functionality looks like this

https://gerrit.googlesource.com/gerrit/+/master/tools/java_doc.defs#32

Genrule supports $(classpath) which expands to the classpath of the java_library.

I was thinking along two lines:

1. Use a configuration fragment to get at the classpath; problem: the Java fragment doesn't expose this.
2. Run javadoc as a java_binary, depending on the things it wants to document. This is fragile (there may be conflicts between the classes that javadoc itself uses, and the to-document classes), and I can't find a jar javadoc inside my JDK installation.

suggestions?

[hanwen]

never mind, PEBKAC.

I shouldn't be looking for a configuration fragment, but for a skylark API provider.

http://www.bazel.io/docs/skylark/lib/JavaSkylarkApiProvider.html#transitive_deps

[pcj]

@f3rdy Here is a javadoc rule for bazel: https://github.com/pubref/rules_apidoc/blob/master/java/README.md#javadoc

[hanwen]

I made one for gerrit too, see https://gerrit.googlesource.com/gerrit/+/master/tools/bzl/javadoc.bzl

[pcj]

Like how it zips it up for you.

[ronshapiro]

I just wrote a similar rule for Dagger here: https://github.com/google/dagger/pull/575/commits/01f96f8b04cddf7f17041a9a0e667d5fc5a55d56

[ittaiz]

Maybe one of the above three should be "cherry-picked" into the main repo? On Fri, 3 Feb 2017 at 20:42 Ron Shapiro notifications@github.com wrote:

I just wrote a similar rule for Dagger here: google/dagger@01f96f8 https://github.com/google/dagger/pull/575/commits/01f96f8b04cddf7f17041a9a0e667d5fc5a55d56

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/bazelbuild/bazel/issues/446#issuecomment-277342885, or mute the thread https://github.com/notifications/unsubscribe-auth/ABUIF9fJbZd7fw3pGXSbkuGZCKZlaJ0jks5rY4MugaJpZM4F7zr0 .

[mboes]

There is also https://github.com/google/bazel-common/tree/master/tools/javadoc.

[bmuschko]

Is there a specific reason why https://github.com/google/bazel-common/blob/master/tools/javadoc/javadoc.bzl isn't part of rules_java? I think it would make a lot of sense to have a one stop solution for Java-based projects.

[tsawada]

There's another implementation available in rules_jvm_external. https://github.com/bazelbuild/rules_jvm_external/blob/master/docs/api.md#javadoc

[olekslitus]

There is also specific rule for Scaladoc. https://github.com/bazelbuild/rules_scala/blob/master/docs/scala_doc.md

[ShreeM01]

Hi there! We're doing a clean up of old issues and will be closing this one. Please reopen if you’d like to discuss anything further. We’ll respond as soon as we have the bandwidth/resources to do so.

[bmuschko]

@kshyanashree Is there a long-term plan for this feature? The Scala rules have a built-in capability, the Java rules don't. IMHO this should look more consistent across rules for different languages.

[alexeagle]

@bmuschko I'm 50% likely to create a rules_docgen that has the consistent rules across all languages

[bmuschko]

@alexeagle Javadoc has an extensive set of configuration options which unlikely will apply to other languages.