doc: add kdoc

src/main/kotlin/org/danilopianini/gradle/git/hooks/AbstractScriptContext.kt

@@ -1,10 +1,12 @@
 package org.danilopianini.gradle.git.hooks
 
+/**
+ * Pre-implements [tasks].
+ */
 abstract class AbstractScriptContext : ScriptContext {
 
     final override fun tasks(first: Any, vararg others: Any, requireSuccess: Boolean) =
         processTasks(first, *others, requireSuccess = requireSuccess)
 
     protected abstract fun processTasks(vararg tasks: Any, requireSuccess: Boolean)
-
-}
+}

src/main/kotlin/org/danilopianini/gradle/git/hooks/CommitMsgScriptContext.kt

@@ -2,8 +2,16 @@ package org.danilopianini.gradle.git.hooks
 
 import java.net.URL
 
+/**
+ * Specialized hook context for commit-msg.
+ */
 class CommitMsgScriptContext : CommonScriptContext("commit-msg") {
 
+    /**
+     * Pre-configures the commit-msg script to check for a valid
+     * [conventional commit](https://www.conventionalcommits.org/)
+     * message.
+     */
     fun conventionalCommits(configuration: ConventionalCommitsContext.() -> Unit = { defaultTypes() }) {
         val types = object : ConventionalCommitsContext {
             override var types = super.types
@@ -21,6 +29,6 @@ class CommitMsgScriptContext : CommonScriptContext("commit-msg") {
     }
 
     companion object {
-        private val SCRIPT_PATH = "org/danilopianini/gradle/git/hooks/conventional-commit-message.sh"
+        private const val SCRIPT_PATH = "org/danilopianini/gradle/git/hooks/conventional-commit-message.sh"
     }
-}
+}

src/main/kotlin/org/danilopianini/gradle/git/hooks/CommonScriptContext.kt

@@ -3,6 +3,9 @@ package org.danilopianini.gradle.git.hooks
 import org.gradle.api.Task
 import org.gradle.api.tasks.TaskProvider
 
+/**
+ * Implements a Script DSL valid for any hook.
+ */
 open class CommonScriptContext(override val name: String) : AbstractScriptContext() {
     final override var script: String = ""
         private set
@@ -64,4 +67,4 @@ open class CommonScriptContext(override val name: String) : AbstractScriptContex
             """.trimIndent()
         }
     }
-}
+}

src/main/kotlin/org/danilopianini/gradle/git/hooks/ConventionalCommitsContext.kt

@@ -1,18 +1,41 @@
 package org.danilopianini.gradle.git.hooks
 
+/**
+ * Specialized DSL element for dealing with [conventional commits](https://www.conventionalcommits.org/).
+ */
 interface ConventionalCommitsContext {
 
+    /**
+     * The selected valid commit types.
+     */
     val types: Set<String> get() = baseTypes
 
+    /**
+     * Adds new supported types.
+     */
     fun types(vararg otherTypes: String): Unit = types(otherTypes.toSet())
 
+    /**
+     * Adds a new supported types.
+     */
     fun types(otherTypes: Set<String>)
 
+    /**
+     * configures all the types in [Companion.defaultTypes].
+     */
     fun defaultTypes() = types(defaultTypes)
 
     companion object {
+
+        /**
+         * Base types: `fix` and `feat`.
+         */
         val baseTypes = setOf("fix", "feat")
 
+        /**
+         * Additional types, as listed in the [conventional commits](https://www.conventionalcommits.org/) webpage,
+         * plus `refactor`, which is commonly used.
+         */
         val defaultTypes: Set<String> = baseTypes + setOf(
             "build",
             "chore",
@@ -25,4 +48,4 @@ interface ConventionalCommitsContext {
             "test",
         )
     }
-}
+}

src/main/kotlin/org/danilopianini/gradle/git/hooks/GitHooksExtension.kt

@@ -4,10 +4,17 @@ import org.gradle.api.initialization.Settings
 import java.io.File
 import java.io.Serializable
 
+/**
+ * DSL entry point, to be applied to [settings].gradle.kts.
+ */
 open class GitHooksExtension(val settings: Settings) : Serializable {
 
     private var hooks: Map<String, String> = emptyMap()
 
+    /**
+     * The git repository root. If unset, it will be searched recursively from the project root towards the
+     * filesystem root.
+     */
     var path: File? = null
         get() =
             field ?: requireNotNull(generateSequence(settings.settingsDir) { it.parentFile }.find { it.isGitRoot() }) {
@@ -21,14 +28,27 @@ open class GitHooksExtension(val settings: Settings) : Serializable {
         hooks = hooks + (context.name to context.apply(configuration).script)
     }
 
+    /**
+     * Defines a new hook with an arbitrary name.
+     */
     fun hook(hookName: String, configuration: ScriptContext.() -> Unit) =
         hook(CommonScriptContext(hookName), configuration)
 
+    /**
+     * Pre-commit hook.
+     */
     fun preCommit(configuration: ScriptContext.() -> Unit) = hook("pre-commit", configuration)
 
+    /**
+     * Commit-msg hook.
+     */
     fun commitMsg(configuration: CommitMsgScriptContext.() -> Unit): Unit =
         hook(CommitMsgScriptContext(), configuration)
 
+    /**
+     * To be called to force the hook creation in case of necessity.
+     * If passed `true`, overwrites in case the script is already present and different than expected.
+     */
     fun createHooks(overwriteExisting: Boolean = false) {
         val root = requireNotNull(path?.takeIf { it.isGitRoot() }) {
             "${path?.absolutePath} is not a valid git root"
@@ -63,6 +83,10 @@ open class GitHooksExtension(val settings: Settings) : Serializable {
 
     companion object {
         private const val serialVersionUID = 1L
+
+        /**
+         * Extension name.
+         */
         const val name: String = "gitHooks"
 
         private fun String.withMargins() = lines().joinToString(separator = "\n|", prefix = "|")
@@ -75,4 +99,4 @@ open class GitHooksExtension(val settings: Settings) : Serializable {
             }
             ?: false
     }
-}
+}

src/main/kotlin/org/danilopianini/gradle/git/hooks/GradleGitHooksPlugin.kt

@@ -5,7 +5,7 @@ import org.gradle.api.initialization.Settings
 import org.gradle.kotlin.dsl.create
 
 /**
- * Just a template.
+ * Creates support for the hooks.
  */
 open class GradleGitHooksPlugin : Plugin<Any> {
     override fun apply(settings: Any) {

src/main/kotlin/org/danilopianini/gradle/git/hooks/ScriptContext.kt

@@ -4,21 +4,70 @@ import org.gradle.api.Task
 import org.gradle.api.tasks.TaskProvider
 import java.net.URL
 
+/**
+ * Collects the DSL elements for defining scripts.
+ */
 interface ScriptContext {
+
+    /**
+     * Hook name.
+     */
     val name: String
+
+    /**
+     * Script content. To be fetched only when the configuration is complete.
+     */
     val script: String
+
+    /**
+     * Appends the result of the provided function to the existing script.
+     */
     fun appendScript(script: () -> String)
+
+    /**
+     * Generates a script from the provided [url].
+     */
     fun from(url: URL) = from("") { url.readText() }
+
+    /**
+     * Generates a script from the provided [url].
+     */
     fun from(url: String) = from(URL(url))
+
+    /**
+     * Generates a script with either the provided [shebang] or with a shebang invoking bash,
+     * and with the result of the provided function.
+     */
     fun from(shebang: String? = "#!/usr/bin/env bash", script: () -> String)
+
+    /**
+     * Adds the provided tasks to the script, by invoking `./gradlew <taskname>`.
+     * By default, a failure of the task implies a failure of the commit.
+     * To run a task without considering the failure critical, pass `[requireSuccess] = false`.
+     */
     fun tasks(name: String, vararg otherNames: String, requireSuccess: Boolean = true) =
         tasks(name as Any, *otherNames, requireSuccess = requireSuccess)
 
+    /**
+     * Adds the provided tasks to the script, by invoking `./gradlew <taskname>`.
+     * By default, a failure of the task implies a failure of the commit.
+     * To run a task without considering the failure critical, pass `[requireSuccess] = false`.
+     */
     fun tasks(task: Task, vararg otherTasks: Task, requireSuccess: Boolean = true) =
         tasks(task as Any, *otherTasks, requireSuccess = requireSuccess)
 
+    /**
+     * Adds the provided tasks to the script, by invoking `./gradlew <taskname>`.
+     * By default, a failure of the task implies a failure of the commit.
+     * To run a task without considering the failure critical, pass `[requireSuccess] = false`.
+     */
     fun tasks(task: TaskProvider<*>, vararg otherTasks: TaskProvider<*>, requireSuccess: Boolean = true) =
         tasks(task as Any, *otherTasks, requireSuccess = requireSuccess)
 
+    /**
+     * Adds the provided tasks to the script, by invoking `./gradlew <taskname>`.
+     * By default, a failure of the task implies a failure of the commit.
+     * To run a task without considering the failure critical, pass `[requireSuccess] = false`.
+     */
     fun tasks(first: Any, vararg others: Any, requireSuccess: Boolean = true)
-}
+}

src/main/kotlin/org/gradle/kotlin/dsl/GradleGitHooksExtensions.kt

@@ -3,7 +3,10 @@ package org.gradle.kotlin.dsl
 import org.danilopianini.gradle.git.hooks.GitHooksExtension
 import org.gradle.api.initialization.Settings
 
+/**
+ * DSL entry point for the git hooks commits.
+ * This function is needed because Gradle doesn't generate accessors for settings extensions.
+ */
 inline fun Settings.gitHooks(configure: GitHooksExtension.() -> Unit) {
-    // This function is needed because Gradle doesn't generate accessors for settings extensions.
     extensions.getByType<GitHooksExtension>().configure()
 }