[doc] Review links in release notes and doc pages

- fix javadoc to find Kotlin files
- fix formatting for language info box
- fix tocmaker link generator

docs/_plugins/javadoc_tag.rb

@@ -107,6 +107,9 @@ class JavadocTag < Liquid::Tag
     super
 
     @doc_ref = doc_ref
+    # in case the doc_ref is a variable (like in %include usage), remember the original value
+    # so that we can restore it after we resolved the variable
+    @initial_doc_ref = doc_ref
   end
 
   def render(var_ctx)
@@ -143,7 +146,8 @@ class JavadocTag < Liquid::Tag
     artifact_name, @type_fqcn = JDocNamespaceDeclaration::parse_fqcn(@type_fqcn, var_ctx)
     resolved_type = JavadocTag::fqcn_type(artifact_name, @type_fqcn)
 
-    diagnose(var_ctx, artifact_name, @type_fqcn, @is_package_ref, resolved_type)
+    # don't warn for unresolved reference when pointing to old api
+    diagnose(var_ctx, artifact_name, @type_fqcn, @is_package_ref, resolved_type) unless @use_previous_api_version
 
     # Expand FQCN of arguments
     @member_suffix.gsub!(JDocNamespaceDeclaration::NAMESPACED_FQCN_REGEX) {|fqcn| JDocNamespaceDeclaration::parse_fqcn(fqcn, var_ctx)[1]}
@@ -161,6 +165,11 @@ class JavadocTag < Liquid::Tag
     api_version = var_ctx["site.pmd." + (@use_previous_api_version ? "previous_version" : "version")]
 
     link_url = doclink(var_ctx["site.javadoc_url_prefix"], artifact_name, api_version, @type_fqcn, @member_suffix, resolved_type)
+
+    # reset the doc_ref, if we resolved a variable reference
+    @doc_ref = @initial_doc_ref
+
+    # return the markup
     markup_link(visible_name, link_url)
   end
 
@@ -248,15 +257,24 @@ class JavadocTag < Liquid::Tag
 
     src_dirs = [
         File.join(artifact_dir, "src", "main", "java"),
+        File.join(artifact_dir, "src", "main", "kotlin"),
         File.join(artifact_dir, "target", "generated-sources", "javacc"),
         File.join(artifact_dir, "target", "generated-sources", "antlr4")
     ].select {|dir| File.exist?(dir)}
 
     targets = src_dirs
                   .map {|dir| File.join(dir, fqcn.split("."))}
-                  .map {|f| File.file?(f + ".java") ? :file : File.exist?(f) ? :package : nil}
+                  .map do |f|
+                    if File.file?(f + ".java") || File.file?(f + ".kt")
+                        next :file
+                    end
+                    if File.exist?(f)
+                        next :package
+                    end
+                    next nil
+                   end
 
-    # consider nested classes (one level is only supported...)
+    # consider nested classes (one level is only supported... and only java...)
     nested_targets = src_dirs
                         .map { |dir| File.join(dir, fqcn.split(".")[0..-2]) }
                         .map {|f| File.file?(f + ".java") ? :nested : File.exist?(f) ? :package : nil}

docs/_plugins/tocmaker_block.rb

@@ -18,7 +18,7 @@ class TocMakerBlock < Liquid::Block
   end
 
   def to_internal_link(header)
-    url = header.downcase.gsub(/\s+/, "-").gsub(/[:\(\)]+/, "")
+    url = header.downcase.gsub(/[^a-zA-Z0-9 -]+/, "").strip.gsub(/\s+/, "-")
 
     "[#{header}](##{url})"
   end