HtmlCodeBlockRenderer improvements:

* split applicability for defined and undefined languages
* make language nullable
* improve documentation for applicability and building of content
* add a lot of tests for multiple renderers combinations

dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/HtmlCodeBlockRenderer.kt

@@ -14,12 +14,36 @@ import kotlinx.html.FlowContent
 public interface HtmlCodeBlockRenderer {
 
     /**
-     * Whether this renderer supports given [language]
+     * Whether this renderer supports rendering Markdown code blocks
+     * for the given [language] explicitly specified in the fenced code block definition,
      */
-    public fun isApplicable(language: String): Boolean
+    public fun isApplicableForDefinedLanguage(language: String): Boolean
 
     /**
-     * Defines how to render [code] for specified [language] via HTML tags
+     * Whether this renderer supports rendering Markdown code blocks
+     * for the given [code] when language is not specified in fenced code blocks
+     * or indented code blocks are used.
      */
-    public fun FlowContent.buildCodeBlock(language: String, code: String)
+    public fun isApplicableForUndefinedLanguage(code: String): Boolean
+
+    /**
+     * Defines how to render [code] for specified [language] via HTML tags.
+     *
+     * The value of the [language] will be the same as in the input Markdown fenced code block definition.
+     * In the following example [language] = `kotlin` and [code] = `val a`:
+     * ~~~markdown
+     * ```kotlin
+     * val a
+     * ```
+     * ~~~
+     * The value of the [language] will be `null` if language is not specified in the fenced code block definition
+     * or indented code blocks are used.
+     * In the following example [language] = `null` and [code] = `val a`:
+     * ~~~markdown
+     * ```
+     * val a
+     * ```
+     * ~~~
+     */
+    public fun FlowContent.buildCodeBlock(language: String?, code: String)
 }

dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/HtmlRenderer.kt

@@ -817,19 +817,25 @@ public open class HtmlRenderer(
         code: ContentCodeBlock,
         pageContext: ContentPage
     ) {
-        customCodeBlockRenderers.forEach { renderer ->
-            if (renderer.isApplicable(code.language)) {
-                // we use first applicable renderer to override rendering
-                val codeText = buildString {
-                    code.children.forEach {
-                        when (it) {
-                            is ContentText -> append(it.text)
-                            is ContentBreakLine -> appendLine()
-                        }
+        if (customCodeBlockRenderers.isNotEmpty()) {
+            val language = code.language.takeIf(String::isNotBlank)
+            val codeText = buildString {
+                code.children.forEach {
+                    when (it) {
+                        is ContentText -> append(it.text)
+                        is ContentBreakLine -> appendLine()
                     }
                 }
-                return with(renderer) {
-                    buildCodeBlock(code.language, codeText)
+            }
+
+            // we use first applicable renderer to override rendering
+            val applicableRenderer = when (language) {
+                null -> customCodeBlockRenderers.firstOrNull { it.isApplicableForUndefinedLanguage(codeText) }
+                else -> customCodeBlockRenderers.firstOrNull { it.isApplicableForDefinedLanguage(language) }
+            }
+            if (applicableRenderer != null) {
+                return with(applicableRenderer) {
+                    buildCodeBlock(language, codeText)
                 }
             }
         }