Attach documentation comments to type alias definitions (#956)

Author: itsmath

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Added
+
+- Documentation comments now attach to type alias definitions ([#956](https://github.com/JohnnyMorganz/luau-lsp/pull/956))
+
 ### Changed
 
 - Sync to upstream Luau 0.664

src/DocumentationParser.cpp

@@ -469,3 +469,35 @@ std::optional<std::string> WorkspaceFolder::getDocumentationForType(const Luau::
     }
     return std::nullopt;
 }
+
+std::optional<std::string> WorkspaceFolder::getDocumentationForAstNode(const Luau::ModuleName& moduleName, const Luau::AstNode* node, const Luau::ScopePtr scope)
+{
+    if (auto ref = node->as<Luau::AstTypeReference>())
+    {
+        if (ref->prefix)
+        {
+            auto importedModuleName = lookupImportedModule(*scope, ref->prefix->value);
+            if (!importedModuleName) 
+                return std::nullopt;
+            auto importedModule = getModule(*importedModuleName);
+            if (!importedModule)
+                return std::nullopt;
+            auto typeLocation = lookupTypeLocation(*importedModule->getModuleScope(), ref->name.value);
+            if (!typeLocation)
+                return std::nullopt;
+            return printMoonwaveDocumentation(getComments(*importedModuleName, *typeLocation));
+        }
+        else
+        {
+            auto typeLocation = lookupTypeLocation(*scope, ref->name.value);
+            if (!typeLocation)
+                return std::nullopt;
+            return printMoonwaveDocumentation(getComments(moduleName, *typeLocation));
+        }
+    }
+    else if (auto alias = node->as<Luau::AstStatTypeAlias>()) 
+    {
+        return printMoonwaveDocumentation(getComments(moduleName, alias->location));
+    }
+    return std::nullopt;
+}

src/include/LSP/Workspace.hpp

@@ -95,6 +95,7 @@ class WorkspaceFolder
 public:
     std::vector<std::string> getComments(const Luau::ModuleName& moduleName, const Luau::Location& node);
     std::optional<std::string> getDocumentationForType(const Luau::TypeId ty);
+    std::optional<std::string> getDocumentationForAstNode(const Luau::ModuleName& moduleName, const Luau::AstNode* node, const Luau::ScopePtr scope);
     std::optional<std::string> getDocumentationForAutocompleteEntry(const std::string& name, const Luau::AutocompleteEntry& entry,
         const std::vector<Luau::AstNode*>& ancestry, const Luau::ModulePtr& localModule);
     std::vector<Reference> findAllTableReferences(const Luau::TypeId ty, std::optional<Luau::Name> property = std::nullopt);

src/operations/Hover.cpp

@@ -350,6 +350,11 @@ std::optional<lsp::Hover> WorkspaceFolder::hover(const lsp::HoverParams& params)
         typeString += kDocumentationBreaker;
         typeString += *documentation;
     }
+    else if (auto documentation = getDocumentationForAstNode(moduleName, node, scope); documentation && !documentation->empty())
+    {
+        typeString += kDocumentationBreaker;
+        typeString += *documentation;
+    }
     else if (documentationLocation)
     {
         if (auto text = printMoonwaveDocumentation(getComments(documentationLocation->moduleName, documentationLocation->location)); !text.empty())

tests/Hover.test.cpp

@@ -307,4 +307,92 @@ TEST_CASE_FIXTURE(Fixture, "includes_documentation_for_a_function_call")
     CHECK_EQ(result->contents.value, codeBlock("luau", "function foo(): ()") + kDocumentationBreaker + "This is documentation for Foo\n");
 }
 
+TEST_CASE_FIXTURE(Fixture, "includes_documentation_for_type_alias_declarations")
+{
+    auto source = R"(
+        --- The metre (or meter in [US spelling]; symbol: m) is the [base unit] of [length]
+        --- in the [International System of Units] (SI)
+        export type Meters = number
+    )";
+
+    auto uri = newDocument("meters.luau", source);
+
+    lsp::HoverParams params;
+    params.textDocument = lsp::TextDocumentIdentifier{uri};
+    params.position = lsp::Position{3, 21};
+
+    auto result = workspace.hover(params);
+    REQUIRE(result);
+    CHECK_EQ(
+        result->contents.value, 
+        codeBlock("luau", "type Meters = number") + 
+        kDocumentationBreaker + 
+        "The metre (or meter in [US spelling]; symbol: m) is the [base unit] of [length]\n" + 
+        "in the [International System of Units] (SI)\n"
+    );
+}
+
+TEST_CASE_FIXTURE(Fixture, "includes_documentation_for_type_alias_declarations_of_intersected_tables")
+{
+    auto source = R"(
+        type Foo = {
+            foo: "Foo",
+        }
+
+        type Bar = {
+            bar: "Bar",
+        }
+
+        --- The terms foobar (/ˈfuːbɑːr/), foo, bar, baz, qux, quux, and others are used as
+        --- metasyntactic variables and placeholder names in computer programming or computer-related documentation
+        export type Foobar = Foo & Bar
+    )";
+
+    auto uri = newDocument("meters.luau", source);
+
+    lsp::HoverParams params;
+    params.textDocument = lsp::TextDocumentIdentifier{uri};
+    params.position = lsp::Position{11, 21};
+
+    auto result = workspace.hover(params);
+    REQUIRE(result);
+    CHECK_EQ(
+        result->contents.value, 
+        codeBlock("luau", "type Foobar = {\n    bar: \"Bar\"\n} & {\n    foo: \"Foo\"\n}") + 
+        kDocumentationBreaker + 
+        "The terms foobar (/ˈfuːbɑːr/), foo, bar, baz, qux, quux, and others are used as\n" +
+        "metasyntactic variables and placeholder names in computer programming or computer-related documentation\n"
+    );
+}
+
+TEST_CASE_FIXTURE(Fixture, "includes_documentation_for_type_references")
+{
+    auto source = R"(
+        type Foo = {
+            foo: "Foo",
+        }
+
+        type Bar = {
+            bar: "Bar",
+        }
+
+        --- This is the intersection of two types
+        export type Foobar = Foo & Bar
+
+        function consumer(value: Foobar)
+        end
+    )";
+
+    auto uri = newDocument("meters.luau", source);
+
+    lsp::HoverParams params;
+    params.textDocument = lsp::TextDocumentIdentifier{uri};
+    params.position = lsp::Position{12, 36};
+
+    auto result = workspace.hover(params);
+    REQUIRE(result);
+    CHECK_EQ(result->contents.value, codeBlock("luau", "type Foobar = {\n    bar: \"Bar\"\n} & {\n    foo: \"Foo\"\n}") + kDocumentationBreaker +
+                                         "This is the intersection of two types\n");
+}
+
 TEST_SUITE_END();