Gradle Will Not Compile Comments

Help/Discuss
1

I’m making a Java Library and I want to provide documentation for it. I’ve used the annotations Name, Description and JavaBean but none provide names descriptions etc. I’ve also used comments, but when I compile them with Gradle, they disappear. Nothing in the Gradle documentation tells you how to compile Javadocs, sources or comments. They just get removed during compilation, I guess.

Source code can be viewed at this repository

What I see in my class
What I see in the decompiled source
What I see in the actual source

Here’s my build.gradle

plugins {
    id 'java-library'
}

group 'me.acaiberii'
version '1.0.6'

repositories {
    mavenCentral()
    maven { url="https://beriidevelopment.github.io/mvn/" }
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.6.0'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine'

    implementation 'com.pushtorefresh:javac_warning_annotation:1.0.0'
}

test {
    useJUnitPlatform()
}

Specs:
Gradle wrapper: 7.1.1
Jupiter-api: 5.6.0

2

Hello,

You have two types of documentation in your code. Annotations that may persist to runtime environment and comments that are processed but ignored by the java compiler. When comments start with /** and are placed in front of API elements they are processed with the Javadoc tool.

Javadoc does not affect performance in Java as all comments are removed at compilation time
Javadoc - Wikipedia

If you configure Gradle to deploy your lib in a Maven repository (also possible with an ivy one I think) it should also deploy a javadoc jar file, a special type of dependency available to your consumers. They can configure their IDE to download it and their IDE will assist them by providing the documentation matching the current context.

Official documentation to configure publication of javadoc and source jars:

https://docs.gradle.org/current/userguide/building_java_projects.html#sec:java_packaging

3

Thank you, sir!

Will the regular

withJavadocJar()
withSourcesJar()

also require you to have a Maven repository? I’m currently manually publishing my JARs.

4

Hi,

Indeed, you have to use the publication feature of Gradle along with a Maven or Ivy repository to use this syntax. You can create a local Maven repository backed by your own filesystem with:

publishing {
    publications {
        javaArtifacts(MavenPublication) {
            from components.java
        }
    }
    repositories {
        maven {
            name = 'local'
            url = layout.buildDirectory.dir('repo') // deploys in build/repo
        }
    }
}

See Maven Publish Plugin for more info

5

No, you don’t need to publish using Gradle.
Those methods add jar tasks for a sources jar and a JavaDoc jar that you can just call like any other task.
If one of the publishing plugins is applied, then it also configures these publications to publish the added jars along with the main artifact.
But there is no necessity to use the publishing mechanism by Gradle.