From f67d929c24babc302eb2807251fc09b084abac2e Mon Sep 17 00:00:00 2001
From: jsmall-nvidia <jsmall@nvidia.com>
Date: Wed, 9 Mar 2022 18:38:00 -0500
Subject: Initial support for documentation extraction in C++ (#2156)

* #include an absolute path didn't work - because paths were taken to always be relative.

* Split doc extractor such that can be used in C++ extractor.

* Compiles. Update the stdlib docs.

* Fix issue on release builds.

* Add support for extracting documentation to C++ extractor.

* Dump out markup.
Make enum value backing type take tokens.

* Node::Type -> Node::Kind

* More improvements around Node::Type -> Node::Kind
---
 source/slang/slang-doc-ast.cpp | 139 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 source/slang/slang-doc-ast.cpp

(limited to 'source/slang/slang-doc-ast.cpp')

diff --git a/source/slang/slang-doc-ast.cpp b/source/slang/slang-doc-ast.cpp
new file mode 100644
index 000000000..8301b1a63
--- /dev/null
+++ b/source/slang/slang-doc-ast.cpp
@@ -0,0 +1,139 @@
+// slang-doc-ast.cpp
+#include "slang-doc-ast.h"
+
+#include "../core/slang-string-util.h"
+
+//#include "slang-ast-builder.h"
+//#include "slang-ast-print.h"
+
+namespace Slang {
+
+/* static */DocMarkupExtractor::SearchStyle ASTMarkupUtil::getSearchStyle(Decl* decl)
+{
+    typedef Extractor::SearchStyle SearchStyle;
+
+    if (auto enumCaseDecl = as<EnumCaseDecl>(decl))
+    {
+        return SearchStyle::EnumCase;
+    }
+    if (auto paramDecl = as<ParamDecl>(decl))
+    {
+        return SearchStyle::Param;
+    }
+    else if (auto callableDecl = as<CallableDecl>(decl))
+    {
+        return SearchStyle::Function;
+    }
+    else if (as<VarDecl>(decl) || as<TypeDefDecl>(decl) || as<AssocTypeDecl>(decl))
+    {
+        return SearchStyle::Variable;
+    }
+    else if (auto genericDecl = as<GenericDecl>(decl))
+    {
+        return getSearchStyle(genericDecl->inner);
+    }
+    else if (as<GenericTypeParamDecl>(decl) || as<GenericValueParamDecl>(decl))
+    {
+        return SearchStyle::GenericParam;
+    }
+    else
+    {
+        // If can't determine just allow before
+        return SearchStyle::Before;
+    }
+}
+
+static void _addDeclRec(Decl* decl, List<Decl*>& outDecls)
+{
+    if (decl == nullptr)
+    {
+        return;
+    }
+
+    // If we don't have a loc, we have no way of locating documentation.
+    if (decl->loc.isValid() || decl->nameAndLoc.loc.isValid())
+    {
+        outDecls.add(decl);
+    }
+    else
+    {
+        SLANG_ASSERT(!"Decl without a location!");
+    }
+
+    if (GenericDecl* genericDecl = as<GenericDecl>(decl))
+    {
+        _addDeclRec(genericDecl->inner, outDecls);
+    }
+
+    if (ContainerDecl* containerDecl = as<ContainerDecl>(decl))
+    {
+        // Add the container - which could be a class, struct, enum, namespace, extension, generic etc.
+        // Now add what the container contains
+        for (Decl* childDecl : containerDecl->members)
+        {
+            _addDeclRec(childDecl, outDecls);
+        }
+    }
+}
+
+/* static */void ASTMarkupUtil::findDecls(ModuleDecl* moduleDecl, List<Decl*>& outDecls)
+{
+    for (Decl* decl : moduleDecl->members)
+    {
+        _addDeclRec(decl, outDecls);
+    }
+}
+
+SlangResult ASTMarkupUtil::extract(ModuleDecl* moduleDecl, SourceManager* sourceManager, DiagnosticSink* sink, ASTMarkup* outDoc)
+{
+    List<Decl*> decls;
+    findDecls(moduleDecl, decls);
+
+    const Index declsCount = decls.getCount();
+
+    List<Extractor::SearchItemInput> inputItems;
+    List<Extractor::SearchItemOutput> outItems;
+
+    {
+        inputItems.setCount(declsCount);
+
+        for (Index i = 0; i < declsCount; ++i)
+        {
+            Decl* decl = decls[i];
+            auto& item = inputItems[i];
+
+            item.sourceLoc = decl->loc.isValid() ? decl->loc : decl->nameAndLoc.loc;
+            // Has to be valid to be lookupable
+            SLANG_ASSERT(item.sourceLoc.isValid());
+
+            item.searchStyle = getSearchStyle(decl);
+        }
+
+        DocMarkupExtractor extractor;
+
+        List<SourceView*> views;
+        SLANG_RETURN_ON_FAIL(extractor.extract(inputItems.getBuffer(), declsCount, sourceManager, sink, views, outItems));
+    }
+
+    // Set back
+    for (Index i = 0; i < declsCount; ++i)
+    {
+        const auto& outputItem = outItems[i];
+        const auto& inputItem = inputItems[outputItem.inputIndex];
+
+        // If we don't know how to search add to the output
+        if (inputItem.searchStyle != Extractor::SearchStyle::None)
+        {
+            Decl* decl = decls[outputItem.inputIndex];
+       
+            // Add to the documentation
+            ASTMarkup::Entry& docEntry = outDoc->addEntry(decl);
+            docEntry.m_markup = outputItem.text;
+            docEntry.m_visibility = outputItem.visibilty;
+        }
+    }
+    
+    return SLANG_OK;
+}
+
+} // namespace Slang
-- 
cgit v1.2.3