From d72030b8762572e9f0e18851b0242c35b2fc1f43 Mon Sep 17 00:00:00 2001
From: Robert Schulze <robert@clickhouse.com>
Date: Wed, 26 Apr 2023 20:33:52 +0000
Subject: [PATCH] Various fixes

---
 src/Common/Documentation.h                    | 42 ++++++++++++++-
 .../System/StorageSystemFunctions.cpp         | 51 +++++++++----------
 2 files changed, 64 insertions(+), 29 deletions(-)

diff --git a/src/Common/Documentation.h b/src/Common/Documentation.h
index 0b0eacbeccd..dea7f28bfc1 100644
--- a/src/Common/Documentation.h
+++ b/src/Common/Documentation.h
@@ -42,27 +42,65 @@ namespace DB
   *
   * Documentation does not support multiple languages.
   * The only available language is English.
+  *
+  * TODO: Allow to specify Syntax, Argument(s) and a Returned Value.
+  * TODO: Organize Examples as a struct of ExampleName, ExampleQuery and ExampleResult.
   */
 struct Documentation
 {
     using Description = std::string;
+
+    using Syntax = std::string;
+
+    using Argument = std::string;
+    using Arguments = std::vector<Argument>;
+
+    using ReturnedValue = std::string;
+
     using ExampleName = std::string;
     using ExampleQuery = std::string;
     using Examples = std::map<ExampleName, ExampleQuery>;
+
     using Category = std::string;
     using Categories = std::vector<Category>;
 
+    using Related = std::string;
+
     Description description;
     Examples examples;
     Categories categories;
 
-    Documentation(Description description_) : description(std::move(description_)) {}
+    Documentation(Description description_) : description(std::move(description_)) {} /// NOLINT
     Documentation(Description description_, Examples examples_) : description(std::move(description_)), examples(std::move(examples_)) {}
     Documentation(Description description_, Examples examples_, Categories categories_)
         : description(std::move(description_)), examples(std::move(examples_)), categories(std::move(categories_)) {}
 
     /// TODO: Please remove this constructor. Documentation should always be non-empty.
-    Documentation() {}
+    Documentation() = default;
+
+    std::string examplesAsString() const
+    {
+        std::string res;
+        for (const auto & [example_name, example_query] : examples)
+        {
+            res += example_name + ":\n\n";
+            res += "```sql\n";
+            res += example_query + "\n";
+            res += "```\n";
+        }
+        return res;
+    }
+
+    std::string categoriesAsString() const
+    {
+        if (categories.empty())
+            return "";
+
+        std::string res = categories[0];
+        for (const auto & category : categories)
+            res += ", " + category;
+        return res;
+    }
 };
 
 }
diff --git a/src/Storages/System/StorageSystemFunctions.cpp b/src/Storages/System/StorageSystemFunctions.cpp
index 29d6b81d528..a4773b0be78 100644
--- a/src/Storages/System/StorageSystemFunctions.cpp
+++ b/src/Storages/System/StorageSystemFunctions.cpp
@@ -22,26 +22,6 @@ enum class FunctionOrigin : Int8
     EXECUTABLE_USER_DEFINED = 2
 };
 
-std::string exampleMapToString( const std::map<std::string, std::string> &example )
-  // in the source, examples for functions are stored in a map. To
-  // create the documentation, we need to convert the map to a string.
-{
-        std::string stringToReturn;
-
-        for (auto iter = example.begin(); iter != example.end(); ++iter){
-           stringToReturn.append("### ");
-           stringToReturn.append(iter->first);
-           stringToReturn.append("\n");
-           stringToReturn.append("```");
-           stringToReturn.append("\n");
-           stringToReturn.append(iter->second);
-           stringToReturn.append("\n");
-           stringToReturn.append("```");
-           stringToReturn.append("\n");
-        }
-        return stringToReturn;
-}
-
 namespace
 {
     template <typename Factory>
@@ -79,19 +59,32 @@ namespace
             if (factory.isAlias(name))
             {
                 res_columns[6]->insertDefault();
-                res_columns[7]->insert(false);
+                res_columns[7]->insertDefault();
+                res_columns[8]->insertDefault();
+                res_columns[9]->insertDefault();
+                res_columns[10]->insertDefault();
+                res_columns[11]->insertDefault();
             }
             else
             {
-                res_columns[6]->insert(factory.getDocumentation(name).description);
-                res_columns[7]->insert(exampleMapToString((factory.getDocumentation(name).examples)));
+                auto documentation = factory.getDocumentation(name);
+                res_columns[6]->insert(documentation.description);
+                res_columns[7]->insertDefault();
+                res_columns[8]->insertDefault();
+                res_columns[9]->insertDefault();
+                res_columns[10]->insert(documentation.examplesAsString());
+                res_columns[11]->insert(documentation.categoriesAsString());
             }
         }
         else
-          {
+        {
             res_columns[6]->insertDefault();
-            res_columns[7]->insert(false);
-          }
+            res_columns[7]->insertDefault();
+            res_columns[8]->insertDefault();
+            res_columns[9]->insertDefault();
+            res_columns[10]->insertDefault();
+            res_columns[11]->insertDefault();
+        }
     }
 }
 
@@ -115,7 +108,11 @@ NamesAndTypesList StorageSystemFunctions::getNamesAndTypes()
         {"create_query", std::make_shared<DataTypeString>()},
         {"origin", std::make_shared<DataTypeEnum8>(getOriginEnumsAndValues())},
         {"description", std::make_shared<DataTypeString>()},
-        {"example", std::make_shared<DataTypeString>()},
+        {"syntax", std::make_shared<DataTypeString>()},
+        {"arguments", std::make_shared<DataTypeString>()},
+        {"returned_value", std::make_shared<DataTypeString>()},
+        {"examples", std::make_shared<DataTypeString>()},
+        {"categories", std::make_shared<DataTypeString>()}
     };
 }