Hey! Let's imagine you have a Kotlin project and y...

# dokka

[Oleg Yukhnevich]

Hey!
Let's imagine you have a Kotlin project and you want to generate Kotlin API documentation in HTML format.
You are using Gradle. Everything is configured. You need to run one task.
Which task name would you expect? Or what will you be looking for?
1. dokkaBuild
2. dokkaGenerate
3. generateDokka
4. generateDocumentation
5. buildDocumentation
6. other? please write in comment any thoughts, ideas, suggestions

[Javier]

I commented something similar to this in the Gradle Slack and the pattern they suggested is toolNameTaskName

Some samples can be spotlessApply or detektName

I would use dokka as general task which runs everything and more granular tasks with dokkaSomeTask

[Javier]

I would avoid general names too for an official plugin like Dokka as generateDocumentation can be a “lifecycle” task if the project does multiple things or have different kind of projects with different documentation plugins

[Sebastian Schuberth]

Something similar probably applies to dokkaBuild as build is a Gradle lifecycle task. So maybe just dokka similar to detekt?

[Javier]

I would expect that dokkaBuild is a task which executes all necessary dokka tasks. So it would be a “dokka lifecycle” task. I have seen both, tool and toolTask.

Should be interesting Gradle would allow aliases

[Sebastian Schuberth]

But what else could belong to a "dokka lifecycle task" other than generating docs?

[Javier]

Html, Markdown and so on

[Javier]

I don’t think the dokka task would do something by itself, some more specific tasks would depend on it based on the plugin configuration

[Sebastian Schuberth]

Ok, makes sense.

[Javier]

dokka {
    html.set(true)
    markdown.set(true)
    javadoc.set(false)
}

That would register the dokkaHtml and dokkaMarkdown tasks that do the actual job. dokka or dokkaBuild do nothing, those tasks are executed if dokka is executed

[Javier]

(I have just invented the configuration, I don't remember it)

[Javier]

I would not use Generate as it usually is to generate code (or anything) that is going to be assembled/built and/or used in the assemble/build tasks (or tasks attached to those tasks). The generated documentation is already "assembled/built".

[Javier]

Additionally, other tools to generate docs use build like mkdocs (both, the tool itself and the unofficial Gradle plugin) and Docusaurus. So it is more friendly to use build over generate

[rnett]

I would not use Generate as it usually is to generate code (or anything) that is going to be assembled/built and/or used in the assemble/build tasks (or tasks attached to those tasks). The generated documentation is already "assembled/built".

We do have muli-module to worry about, I'd suggest dokkaGenerate to generate this module's docs, and dokkaBuild (or assemble) to include any multi-module docs, depending on how exactly that's going to look

[Javier]

Do you mean registering dokkaBuild only at the root project? That is not a good practice

[Javier]

For multimodule dokka should do the same kover is doing

[rnett]

No, I'd think that generate would generate just this module's docs, and the build would include dependencies (like kover). But that's only really relevant if generate can't just include dependencies by itself

[andries.fc]

if all project’s documentation is using dokka, then why not just: generateProjectDocs? Assuming there are sub projects.

[Robert Jaros]

I don't think guessing the correct task name is a good idea at all. I think the task name can be anything, as long as it is clearly documented on the project website and with gradle tasks output.

[Javier]

Well, a good name is important as it is easy to remember dokka or dokkaBuild without having to go to the docs to remember a “random name” as it follows a pattern used by other plugins.

[Ignat Beresnev]

Thank you all for sharing your thoughts! It's really valuable

A bit of context sharing to align expectations: we're looking to significantly simplify the Gradle plugin, removing some things that are possible and taken for granted now, but that our users (especially Kotlin/Gradle beginners) find confusing.

UX research has shown two major problems in the current plugin that are related to task names:
• Too many tasks to choose from: dokkaHtml, dokkaPartial, dokkaGfm, dokkaJekyll, dokkaJavadoc.
• Separate tasks for multimodule projects, so dokkaHtmlMultiModule, dokkaGfmMultiModule and so on.
While most of you are Dokka and Gradle power users and don't have that problem, it really is confusing for beginners that might not even realize they have a multi-module project and not understand the difference between the formats 🙂

So ideally (if possible), we'd like to provide a single user-facing task that will just generate the documentation (HTML by default), both in single-project and in multi-project builds.

[Javier]

As a user I would expect enable the output formats in the DSL (and the rest of options) and run dokka instead of needing to run any more specific task.

Similar to running assemble and not any compile task individually.

[CLOVIS]

^ while I agree with the above message, I still expect a different task to exist per format. The DSL should only change which tasks the default Dokka task depends on, not their existence

[solonovamax]

idk, tbh the task name makes little to no difference. just choose one and stick with it.

usually I'll just invoke build, which has a task dep on dokka. or, I'll invoke it from my IDE, where I can look at the "documentation" category to find the task name