External documentation for Gradle project dependencies

Please see https://dzone.com/articles/gradle-goodness-download-javadoc-files-for-depende.

Adding IDEA-specific stuff is ugly. I opened a ticket for this: https://youtrack.jetbrains.com/issue/IDEA-286107

For Gradle projects sources of the project library dependencies should be downloaded by default during the project import. If one needs a custom behaviour (for sources/javadoc), it can be configured in Gradle build file as per Gradle's documentation: https://docs.gradle.org/current/dsl/org.gradle.plugins.ide.idea.model.IdeaModule.html. This behaviour is by Gradle and IntelliJ IDEA's design.

If downloading by default does not work, there could be some reason/issue for this. Please check that sources and docs exist for the dependencies and the Gradle command line build for the project pulls them into local Maven repository or Gradle cache.

If issue remains, please clarify if sources/docs are available in local repository/cache. Attach idea.log file (use Help | Show Log in ... action to reveal it) after IDE restart and reproducing (Reload action in gradle tool window for the project). Thank you.

Thank you Zeljko Trogrlic  for this question, it helped me arrive at what you asked.
I share with world the solution for this

context:
$gradlew --version
Gradle 8.14.2

With some help of chatgpt and after finding this thread on google:

me(chatgpt):why is my intellij not fetching documentation automatically?
chatgpt: bad answer…
google: intellij gradle Download external documentation
I find this thread. still not satisfactory…

me(chatgpt):

I found online that I need to change build.gradle.kts:

apply {
   plugin 'java'
   plugin 'idea'
}
idea {
   module {
       downloadJavadoc = true
   }
}

How to add this without changing build.gradle.kts which and having private (non-git) settings?

chatgpt(after some errors):
 

Here’s a concise guide to three ways you can enable downloadSources and downloadJavadoc for just one project—without touching its checked‑in build.gradle.kts. Pick the one that best fits your workflow:

1. Global Init Script (~/.gradle/init.gradle.kts)

What it is

A single “init” file in your Gradle user home that runs for every build you do—but you guard it so it only applies to your one project.

Setup Steps

1. Create or open ~/.gradle/init.gradle.kts.

2. 
   import org.gradle.plugins.ide.idea.model.IdeaModel
   
   allprojects {
     // only apply to your project by name
     if (rootProject.name == "my-app") {
       plugins.withId("idea") {
         extensions.configure(IdeaModel::class.java) {
           module {
             isDownloadSources = true
             isDownloadJavadoc = true
           }
         }
       }
     }
   }
   

    

3. Replace "my-app" with the exact name of your root project (as defined in settings.gradle.kts).
4. Restart IntelliJ or hit Refresh in the Gradle tool window.

Pros & Cons

• Pros: Single file to manage.
• Cons: Lives in your home directory—if you switch machines, you must copy it.

2. Project‑Local Init Script (gradle/init.d/…)

What it is

A per‑project Gradle init script that sits alongside your code but never gets committed (you git‑ignore it).

Setup Steps

1. In your project root, create a folder: gradle/init.d/ 
2. Inside it, create e.g. idea-download-docs.gradle.kts

3. import org.gradle.plugins.ide.idea.model.IdeaModel
   
   // adjust "my-app" to your rootProject.name if needed
   if (gradle.rootProject.name == "my-app") {
     gradle.rootProject.plugins.withId("idea") {
       gradle.rootProject.extensions.configure(IdeaModel::class.java) {
         module {
           isDownloadSources = true
           isDownloadJavadoc = true
         }
       }
     }
   }
   

4. Add gradle/init.d/ to your .gitignore.
5. Refresh the Gradle project in IntelliJ.

Pros & Cons

• Pros: Config lives alongside the project; no home‑directory juggling.
• Cons: You must remember to ignore the folder (otherwise others see it).

3. Global “All‑Projects” Init Script Without Name Guard

What it is

A truly global init script that blindly applies to all Gradle builds on your machine. Use this only if you never mind sources/docs for every project.

Setup Steps

1. In ~/.gradle/init.gradle.kts, add:

2. import org.gradle.plugins.ide.idea.model.IdeaModel
   
   allprojects {
     plugins.withId("idea") {
       extensions.configure(IdeaModel::class.java) {
         module {
           isDownloadSources = true
           isDownloadJavadoc = true
         }
       }
    }
   }
   

3. Restart IntelliJ or re‑import any Gradle project.

Pros & Cons

• Pros: Zero per‑project setup; you never worry about docs again.
• Cons: You’ll download sources/javadoc even for small toy builds or CI runs—wastes bandwidth and disk.

Choosing the Right Option

1. If you share machines or dotfiles, the global‑with‑guard script keeps you in sync.
2. If you like per‑repo config, the gradle/init.d/ approach is most self‑contained.
3. If you never mind extra downloads, the plain global init is the simplest.

Once you’ve picked and installed one of the above, just hit Refresh in IntelliJ’s Gradle tool window (or restart the IDE), and from then on you’ll get sources & Javadoc automatically—no dirty diffs in your build.gradle.kts.