1

I want to release a project on Github. It works and I can retrieve it as dependency via Gradle. But the JavaDoc is missing.

Message:

Note: This element neither has attached source nor attached Javadoc and hence no Javadoc could be found.

Do i need to build a JAR ? Or is there any way to add my JavaDoc to the Project, so JavaDoc is availiable when it is build with gradle?

Zabuzard
  • 25,064
  • 8
  • 58
  • 82
Luxusproblem
  • 1,913
  • 11
  • 23
  • Usually you would ship your documentation as separate jar. And/or offer it online as website (for example via github.io). The user can then simply tell his IDE where to get the documentation from (webpage or jar for example). – Zabuzard Oct 21 '19 at 21:48

2 Answers2

1

Do not release JavaDoc to (a) Github (repository), because JavaDoc is derivation products from Java source code.

Let's thinking, when you change comment in JavaDocs, your JavaDocs Github repository also need changing. It is redundancy.

Let 's see few well-known Java projects on Github, such as, https://github.com/spring-projects/spring-boot , they don't put any JavaDoc (HTML files) in a GitHub repository.

Task generate JavaDocs by Gradle: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.javadoc.Javadoc.html

Vy Do
  • 46,709
  • 59
  • 215
  • 313
  • Can you also propose an alternative of how to distribute it? For example as `jar` on the download section or as website, for example using `github.io`? Maybe backing with some example projects, as you already did. – Zabuzard Oct 21 '19 at 22:07
  • Let's see https://stackoverflow.com/a/45998252/3728901 ,then, put JavaDoc HTML files to a directory on web server. – Vy Do Oct 21 '19 at 22:25
  • @DoNhuVy And that would generate the nessecary JavaDocs when building with Gradle ? So that they are availiable as Dependency ? – Luxusproblem Oct 21 '19 at 22:43
  • Gradle is a build took, not a dependency, you no need more any dependency. – Vy Do Oct 21 '19 at 22:47
  • @DoNhuVy I generated the JavaDoc with Gradle. That works fine. I re-released my small project, and put the dependency in the othery gradle build. Everything works fine. Except the Documentation. Even when I run the "gradle javadoc" task. Nothing in "my" dependency is documented. It is btw a standard build. no extraordinary file structure or something like that. – Luxusproblem Oct 21 '19 at 22:57
  • "Nothing in your dependency is documented" --> it works as expected. – Vy Do Oct 21 '19 at 23:05
1

You could use the docs/ folder or the gh-pages branchin order to publish your generated JavaDoc on GitHub.

Example: ebourg.github.io/jsign/apidocs/ from github.com/ebourg/jsign/tree/gh-pages.

The alternative is to publish your deliverables (jars and javadoc.jar) to a binary referentials (Central Maven or Bintray) and let a third party service exposes the Javadoc for you.
See "www.javadoc.io"

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250