Add parameter information to docs

Author: carlosdelest

docs/reference/esql/functions/kibana/definition/match.json

@@ -703,8 +703,8 @@ FROM books
 // tag::match-with-named-function-params-result[]
 title:text
 The Hobbit or There and Back Again
-;
 // end::match-with-named-function-params-result[]
+;
 
 testMatchWithOptionsMinimumShouldMatch
 required_capability: match_function

docs/reference/esql/functions/kibana/definition/match_operator.json

@@ -183,31 +183,37 @@ public Match(
             params = {
                 @MapParam.MapParamEntry(
                     name = "analyzer",
+                    type = "keyword",
                     valueHint = { "standard" },
                     description = "Analyzer used to convert the text in the query value into token."
                 ),
                 @MapParam.MapParamEntry(
                     name = "auto_generate_synonyms_phrase_query",
+                    type = "boolean",
                     valueHint = { "true", "false" },
                     description = "If true, match phrase queries are automatically created for multi-term synonyms."
                 ),
                 @MapParam.MapParamEntry(
                     name = "fuzziness",
+                    type = "keyword",
                     valueHint = { "AUTO", "1", "2" },
                     description = "Maximum edit distance allowed for matching."
                 ),
                 @MapParam.MapParamEntry(
                     name = "boost",
+                    type = "float",
                     valueHint = { "2.5" },
                     description = "Floating point number used to decrease or increase the relevance scores of the query."
                 ),
                 @MapParam.MapParamEntry(
                     name = "fuzzy_transpositions",
+                    type = "boolean",
                     valueHint = { "true", "false" },
                     description = "If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba)."
                 ),
                 @MapParam.MapParamEntry(
                     name = "fuzzy_rewrite",
+                    type = "keyword",
                     valueHint = {
                         "constant_score_blended",
                         "constant_score",
@@ -219,27 +225,32 @@ public Match(
                 ),
                 @MapParam.MapParamEntry(
                     name = "lenient",
+                    type = "boolean",
                     valueHint = { "true", "false" },
                     description = "If false, format-based errors, such as providing a text query value for a numeric field, are returned."
                 ),
                 @MapParam.MapParamEntry(
                     name = "max_expansions",
+                    type = "integer",
                     valueHint = { "50" },
                     description = "Maximum number of terms to which the query will expand."
                 ),
                 @MapParam.MapParamEntry(
                     name = "minimum_should_match",
+                    type = "integer",
                     valueHint = { "2" },
                     description = "Minimum number of clauses that must match for a document to be returned."
                 ),
                 @MapParam.MapParamEntry(
                     name = "operator",
+                    type = "keyword",
                     valueHint = { "AND", "OR" },
                     description = "Boolean logic used to interpret text in the query value"
                 ),
                 @MapParam.MapParamEntry(name = "prefix_length", valueHint = { "1" }, description = ""),
                 @MapParam.MapParamEntry(
                     name = "zero_terms_query",
+                    type = "keyword",
                     valueHint = { "none", "all" },
                     description = "Number of beginning characters left unchanged for fuzzy matching."
                 ) },

docs/reference/esql/functions/kibana/docs/match_operator.md

@@ -90,6 +90,7 @@
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Optional;
 import java.util.Set;
 import java.util.TreeSet;
 import java.util.stream.Collectors;
@@ -926,9 +927,17 @@ public static void renderDocs() throws IOException {
             renderParametersList(description.argNames(), description.argDescriptions());
             FunctionInfo info = EsqlFunctionRegistry.functionInfo(definition);
             renderDescription(description.description(), info.detailedDescription(), info.note());
+            Optional<EsqlFunctionRegistry.ArgSignature> mapArgSignature = description.args()
+                .stream()
+                .filter(EsqlFunctionRegistry.ArgSignature::mapArg)
+                .findFirst();
+            boolean hasFunctionOptions = mapArgSignature.isPresent();
+            if (hasFunctionOptions) {
+                renderFunctionNamedParams((EsqlFunctionRegistry.MapArgSignature) mapArgSignature.get());
+            }
             boolean hasExamples = renderExamples(info);
             boolean hasAppendix = renderAppendix(info.appendix());
-            renderFullLayout(name, info.preview(), hasExamples, hasAppendix);
+            renderFullLayout(name, info.preview(), hasExamples, hasAppendix, hasFunctionOptions);
             renderKibanaInlineDocs(name, info);
             renderKibanaFunctionDefinition(name, info, description.args(), description.variadic());
             return;
@@ -947,8 +956,11 @@ public static void renderDocs() throws IOException {
     private static void renderTypes(List<EsqlFunctionRegistry.ArgSignature> args) throws IOException {
         StringBuilder header = new StringBuilder();
         List<String> argNames = args.stream().map(EsqlFunctionRegistry.ArgSignature::name).toList();
-        for (String arg : argNames) {
-            header.append(arg).append(" | ");
+        for (EsqlFunctionRegistry.ArgSignature arg : args) {
+            if (arg.optional()) {
+                header.append("(optional) ");
+            }
+            header.append(arg.name()).append(" | ");
         }
         header.append("result");
 
@@ -962,12 +974,15 @@ private static void renderTypes(List<EsqlFunctionRegistry.ArgSignature> args) th
             }
             StringBuilder b = new StringBuilder();
             for (int i = 0; i < sig.getKey().size(); i++) {
+
                 DataType argType = sig.getKey().get(i);
-                if (args.get(i).mapArg()) {
-                    b.append("map | ");
+                EsqlFunctionRegistry.ArgSignature argSignature = args.get(i);
+                if (argSignature.mapArg()) {
+                    b.append("named parameters");
                 } else {
-                    b.append(argType.esNameIfPossible()).append(" | ");
+                    b.append(argType.esNameIfPossible());
                 }
+                b.append(" | ");
             }
             b.append("| ".repeat(argNames.size() - sig.getKey().size()));
             b.append(sig.getValue().esNameIfPossible());
@@ -988,6 +1003,27 @@ private static void renderTypes(List<EsqlFunctionRegistry.ArgSignature> args) th
         writeToTempDir("types", rendered, "asciidoc");
     }
 
+    private static void renderFunctionNamedParams(EsqlFunctionRegistry.MapArgSignature mapArgSignature) throws IOException {
+        String header = "name | types | description";
+
+        List<String> table = new ArrayList<>();
+        for (Map.Entry<String, EsqlFunctionRegistry.MapEntryArgSignature> argSignatureEntry : mapArgSignature.mapParams().entrySet()) {
+            StringBuilder builder = new StringBuilder();
+            EsqlFunctionRegistry.MapEntryArgSignature arg = argSignatureEntry.getValue();
+            builder.append(arg.name()).append(" | ").append(arg.type()).append(" | ").append(arg.description());
+            table.add(builder.toString());
+        }
+
+        String rendered = DOCS_WARNING + """
+            *Supported function named parameters*
+
+            [%header.monospaced.styled,format=dsv,separator=|]
+            |===
+            """ + header + "\n" + table.stream().collect(Collectors.joining("\n")) + "\n|===\n";
+        LogManager.getLogger(getTestClass()).info("Writing function named parameters for [{}]:\n{}", functionName(), rendered);
+        writeToTempDir("functionNamedParams", rendered, "asciidoc");
+    }
+
     private static void renderParametersList(List<String> argNames, List<String> argDescriptions) throws IOException {
         StringBuilder builder = new StringBuilder();
         builder.append(DOCS_WARNING);
@@ -1068,7 +1104,8 @@ private static boolean renderAppendix(String appendix) throws IOException {
         return true;
     }
 
-    private static void renderFullLayout(String name, boolean preview, boolean hasExamples, boolean hasAppendix) throws IOException {
+    private static void renderFullLayout(String name, boolean preview, boolean hasExamples, boolean hasAppendix, boolean hasFunctionOptions)
+        throws IOException {
         String rendered = DOCS_WARNING + """
             [discrete]
             [[esql-$NAME$]]
@@ -1085,6 +1122,13 @@ private static void renderFullLayout(String name, boolean preview, boolean hasEx
             """.replace("$NAME$", name)
             .replace("$UPPER_NAME$", name.toUpperCase(Locale.ROOT))
             .replace("$PREVIEW_CALLOUT$", preview ? PREVIEW_CALLOUT : "");
+        if (hasFunctionOptions) {
+            rendered += "ifeval::[\"{release-state}\"==\"unreleased\"]\n"
+                + "//include::../optionalFunctionParams/"
+                + name
+                + ".asciidoc[]\n"
+                + "endif::[]\n";
+        }
         if (hasExamples) {
             rendered += "include::../examples/" + name + ".asciidoc[]\n";
         }