YQL-20112: Support experimental documentation

LSP supports the following propoerty of the
completion item, that supports Markdown format:

```
/**
 * A human-readable string that represents a doc-comment.
 */
documentation?: string | MarkupContent;
```

I added docs only for a few items just to check a
look in the UI. Also some docs are shortened.

Documentation is opt-in decorator for a
NameService. Because it is not needed in the
YDB CLI, for example.
commit_hash:b400ed1224be2906b7fb1da29e9c97aa7578d710

Author: vityaman

yql/essentials/sql/v1/complete/name/service/docs/documentation.cpp

@@ -0,0 +1,37 @@
+#include "documentation.h"
+
+#include <yql/essentials/sql/v1/complete/name/service/name_service.h>
+
+namespace NSQLComplete {
+
+    namespace {
+
+        class TDocumentation: public IDocumentation {
+        public:
+            explicit TDocumentation(TDocByNormalizedNameMap docs)
+                : Docs_(std::move(docs))
+            {
+            }
+
+            TMaybe<TString> Lookup(TStringBuf name) const override {
+                if (auto* ptr = Docs_.FindPtr(Normalized(name))) {
+                    return *ptr;
+                }
+                return Nothing();
+            }
+
+        private:
+            TString Normalized(TStringBuf name) const {
+                return NormalizeName(name);
+            }
+
+            TDocByNormalizedNameMap Docs_;
+        };
+
+    } // namespace
+
+    IDocumentation::TPtr MakeStaticDocumentation(TDocByNormalizedNameMap docs) {
+        return new TDocumentation(std::move(docs));
+    }
+
+} // namespace NSQLComplete

yql/essentials/sql/v1/complete/name/service/docs/documentation.h

@@ -0,0 +1,19 @@
+#pragma once
+
+#include <util/generic/ptr.h>
+#include <util/generic/maybe.h>
+
+namespace NSQLComplete {
+
+    class IDocumentation: public TThrRefBase {
+    public:
+        using TPtr = TIntrusivePtr<IDocumentation>;
+
+        virtual TMaybe<TString> Lookup(TStringBuf name) const = 0;
+    };
+
+    using TDocByNormalizedNameMap = THashMap<TString, TString>;
+
+    IDocumentation::TPtr MakeStaticDocumentation(TDocByNormalizedNameMap docs);
+
+} // namespace NSQLComplete

yql/essentials/sql/v1/complete/name/service/docs/name_service.cpp

@@ -0,0 +1,45 @@
+#include "name_service.h"
+
+namespace NSQLComplete {
+
+    namespace {
+
+        class TNameService: public INameService {
+        public:
+            TNameService(IDocumentation::TPtr docs, INameService::TPtr origin)
+                : Docs_(std::move(docs))
+                , Origin_(std::move(origin))
+            {
+            }
+
+            NThreading::TFuture<TNameResponse> Lookup(const TNameRequest& request) const override {
+                return Origin_->Lookup(request).Apply([docs = Docs_](auto f) {
+                    TNameResponse response = f.ExtractValue();
+                    for (TGenericName& name : response.RankedNames) {
+                        name = std::visit([&](auto&& name) -> TGenericName {
+                            using T = std::decay_t<decltype(name)>;
+
+                            if constexpr (std::is_base_of_v<TDescribed, T> &&
+                                          std::is_base_of_v<TIdentifier, T>) {
+                                name.Description = docs->Lookup(name.Identifier);
+                            }
+
+                            return std::move(name);
+                        }, std::move(name));
+                    }
+                    return response;
+                });
+            }
+
+        private:
+            IDocumentation::TPtr Docs_;
+            INameService::TPtr Origin_;
+        };
+
+    } // namespace
+
+    INameService::TPtr MakeDocumentingNameService(IDocumentation::TPtr docs, INameService::TPtr origin) {
+        return new TNameService(std::move(docs), std::move(origin));
+    }
+
+} // namespace NSQLComplete

yql/essentials/sql/v1/complete/name/service/docs/name_service.h

@@ -0,0 +1,11 @@
+#pragma once
+
+#include "documentation.h"
+
+#include <yql/essentials/sql/v1/complete/name/service/name_service.h>
+
+namespace NSQLComplete {
+
+    INameService::TPtr MakeDocumentingNameService(IDocumentation::TPtr docs, INameService::TPtr origin);
+
+} // namespace NSQLComplete

yql/essentials/sql/v1/complete/name/service/docs/ya.make

@@ -0,0 +1,12 @@
+LIBRARY()
+
+SRCS(
+    documentation.cpp
+    name_service.cpp
+)
+
+PEERDIR(
+    yql/essentials/sql/v1/complete/name/service
+)
+
+END()

yql/essentials/sql/v1/complete/name/service/name_service.h

@@ -20,6 +20,10 @@ namespace NSQLComplete {
         TString Namespace;
     };
 
+    struct TDescribed {
+        TMaybe<TString> Description;
+    };
+
     struct TKeyword {
         TString Content;
     };
@@ -40,7 +44,7 @@ namespace NSQLComplete {
         EKind Kind = EKind::Simple;
     };
 
-    struct TFunctionName: TIdentifier {
+    struct TFunctionName: TIdentifier, TDescribed {
         struct TConstraints: TNamespaced {};
     };
 

yql/essentials/sql/v1/complete/name/service/ya.make

@@ -15,6 +15,7 @@ RECURSE(
     binding
     cluster
     column
+    docs
     impatient
     ranking
     schema

yql/essentials/sql/v1/complete/name_mapping.cpp

@@ -143,6 +143,7 @@ namespace NSQLComplete {
     TCandidate ToCandidate(TGenericName generic, TLocalSyntaxContext& local) {
         return std::visit([&](auto&& name) -> TCandidate {
             using T = std::decay_t<decltype(name)>;
+
             constexpr bool IsContextSensitive =
                 std::is_same_v<T, TKeyword> ||
                 std::is_same_v<T, TFolderName> ||
@@ -151,11 +152,24 @@ namespace NSQLComplete {
                 std::is_same_v<T, TBindingName> ||
                 std::is_same_v<T, TUnknownName>;
 
+            constexpr bool IsDocumented =
+                std::is_base_of_v<TDescribed, T>;
+
+            TMaybe<TString> documentation;
+            if constexpr (IsDocumented) {
+                documentation = std::move(name.Description);
+            }
+
+            TCandidate candidate;
             if constexpr (IsContextSensitive) {
-                return ToCandidate(std::move(name), local);
+                candidate = ToCandidate(std::move(name), local);
             } else {
-                return ToCandidate(std::move(name));
+                candidate = ToCandidate(std::move(name));
             }
+
+            candidate.Documentation = std::move(documentation);
+
+            return candidate;
         }, std::move(generic));
     }
 

yql/essentials/sql/v1/complete/sql_complete.h

@@ -39,6 +39,7 @@ namespace NSQLComplete {
         ECandidateKind Kind;
         TString Content;
         size_t CursorShift = 0;
+        TMaybe<TString> Documentation = Nothing();
 
         friend bool operator==(const TCandidate& lhs, const TCandidate& rhs) = default;