49 lines
1.6 KiB
Plaintext
49 lines
1.6 KiB
Plaintext
== Why is this an issue?
|
|
|
|
The actions performed by a task are often too complex or specific,
|
|
and the task name cannot describe the task's action sufficiently well.
|
|
Moreover, build scripts usually consist of many tasks - whether explicitly defined or implicitly by the applied plugins -
|
|
so a structure is required to help the user navigate through existing tasks.
|
|
|
|
Therefore, tasks should define a `description` and `group` to provide documentation and categorization for the user.
|
|
|
|
=== What is the potential impact?
|
|
|
|
==== Improve task discoverability
|
|
|
|
Users can find tasks easier and understand their purpose if they contain a description and are grouped into categories.
|
|
|
|
== How to fix it
|
|
|
|
Assign the `description` and `group` properties in your task configuration.
|
|
|
|
=== Code examples
|
|
|
|
==== Noncompliant code example
|
|
|
|
[source,kotlin,diff-id=1,diff-type=noncompliant]
|
|
----
|
|
tasks.register<DocsGenerate>("generateHtmlDocs") { // Noncompliant, does neither define "description" and "group"
|
|
title.set("Project docs")
|
|
outputDir.set(layout.buildDirectory.dir("docs"))
|
|
}
|
|
----
|
|
|
|
==== Compliant solution
|
|
|
|
[source,kotlin,diff-id=1,diff-type=compliant]
|
|
----
|
|
tasks.register<DocsGenerate>("generateHtmlDocs") { // Compliant, defines "description" and "group"
|
|
description = "Generates the HTML documentation for this project."
|
|
group = JavaBasePlugin.DOCUMENTATION_GROUP
|
|
title.set("Project docs")
|
|
outputDir.set(layout.buildDirectory.dir("docs"))
|
|
}
|
|
----
|
|
|
|
== Resources
|
|
|
|
=== Documentation
|
|
|
|
* https://docs.gradle.org/current/userguide/authoring_maintainable_build_scripts.html#sec:improving_task_discoverability[Gradle Documentation - Improve task discoverability]
|