Fix external documentation link default values

[adam-enko]

Prevent the default value of true from overriding the specific values provided from the top level Dokka DSL.

KT-70908

[Tapchicoma]

Hm, why does convention not work here?

[adam-enko]

I believe it gets overridden by the configureEach {} above, which sets the convention to true.

dokka/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt

Lines 214 to 218 in f4b0ad9

	externalDocumentationLinks {
	configureEach {
	enabled.convention(true)
	packageListUrl.convention(url.map { it.appendPath("package-list") })
	}

[Tapchicoma]

Could it skip these known names like if(name !in setOf("jdk", "kotlinStdlib", "androidSdk", "androidX"))?

Usually using actual values instead of conventions in entities that could be configured by users are a code smell.

[adam-enko]

I agree that it looks unusual, but I think it's correct to use set() instead of `convention() here.

The root cause of the non-idiomatic behaviour is that the Dokka DSL is unusual. It has two ways of configuring whether the external links are active - either via DokkaSourceSetSpec#enableAndroidDocumentationLink or via DokkaExternalDocumentationLinkSpec#getEnabled. Why are there two? Which one should take priority? This should be tidied instead.

The actual DSL is less important in DGPv2: the values are determined automatically based on the buildscript environment (e.g. if AGP is applied), so hopefully users don't configure them manually.

In the future I would like to revisit the external documentation links to improve them. I'd like to add a lot more of them, and to dynamically enable/disable them based on the classpath, so no manual configuration is required at all. And to make it easier to register new ones.

[Tapchicoma]

Please create an issue for this to not forget about it

[adam-enko]

https://youtrack.jetbrains.com/issue/KT-71894/Revisit-external-documentation-links-in-DGPv2