ExternalDocumentationLinks: Use name as convention value for url

[hfhbd]

Current behavior:

externalDocumentationLinks {
  register("serialization") {
    url("https://kotlin.github.io/kotlinx.serialization")
  }
}

New design:

externalDocumentationLinks {
  register("https://kotlin.github.io/kotlinx.serialization")
}

I guess you don't use the name at all?

[aSemy]

Thanks for the report!

My intention for not using the URL for the name is to allow for Gradle to generate Kotlin DSL accessors. This means that some common ones can be added in Dokkatoo, or I can define my own in a convention plugin, and they'll be easier to manually enable/disable in build scripts. E.g.

dokkatoo {
  dokkatooSourceSets.named("main") { 
    externalDocumentationLinks {
      kotlinStdlib {
        enabled = true
      }
    }
  }
}

Although Gradle doesn't generate accessors for nested types like this for some reason. Maybe it will work one day?

I can see that the current definition could be less verbose. What do you think about adding a helper function? E.g.

dokkatoo {
  dokkatooSourceSets.configureEach {
    externalDocumentationLink("https://docs.gradle.org/${gradle.gradleVersion}/javadoc/")
  }
}

Under the hood this would automatically add a external doc link, either using the URL as the name, though perhaps it could try and generate a DSL accessor compatible name.

What would be cool is to add a lot more external doc links. Some common ones are already added. And then, even if the Kotlin DSL accessor doesn't work, they could even be automatically enabled if a dependency is detected.

[hfhbd]

The helper method sounds good too.

Regarding more external doc links, do you have a name schema for kotlinx, eg kotlinx-serialization?

[EdricChan03]

Although Gradle doesn't generate accessors for nested types like this for some reason. Maybe it will work one day?

Late to the conversation, but this is filed as a feature at gradle/gradle#9264 :)