Doc improvements (#1729)

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

* Split out AST 'printing'.

* Replace listener with List<Section>

* Section -> Part.

* Kind -> Type Flags -> Kind for ASTPrinter::Part

* Improve comments around ASTPrinter.

* toString -> toText on Val derived types. toText appends to a StringBuilder.

* Added toSlice free function.
Added operator<< for Val derived types.
Use << where appropriate in doing toText.

* More work at mark down output.

* Fill in sourceloc for enum case.
Add more sophisticated location determination for EnumCase.
Refactored documentation output into DocMarkdownWriter.

* Improvements for sig output.

1 files changed, 4 insertions, 194 deletions

diff --git a/source/slang/slang-check-overload.cpp b/source/slang/slang-check-overload.cpp
index a4a55c8ce..c4e4cbde4 100644
--- a/source/slang/slang-check-overload.cpp
+++ b/source/slang/slang-check-overload.cpp
@@ -2,6 +2,7 @@
 #include "slang-check-impl.h"
 
 #include "slang-lookup.h"
+#include "slang-ast-print.h"
 
 // This file implements semantic checking logic related
 // to resolving overloading call operations, by checking
@@ -531,7 +532,7 @@ namespace Slang
                 Diagnostics::genericArgumentInferenceFailed,
                 callString);
 
-            String declString = getDeclSignatureString(candidate.item);
+            String declString = ASTPrinter::getDeclSignatureString(candidate.item, m_astBuilder);
             getSink()->diagnose(candidate.item.declRef, Diagnostics::genericSignatureTried, declString);
             goto error;
         }
@@ -1268,197 +1269,6 @@ namespace Slang
         }
     }
 
-    void SemanticsVisitor::formatType(StringBuilder& sb, Type* type)
-    {
-        sb << type->toString();
-    }
-
-    void SemanticsVisitor::formatVal(StringBuilder& sb, Val* val)
-    {
-        sb << val->toString();
-    }
-
-    static void formatDeclName(StringBuilder& sb, Decl* decl)
-    {
-        if(as<ConstructorDecl>(decl))
-        {
-            sb << "init";
-        }
-        else if(as<SubscriptDecl>(decl))
-        {
-            sb << "subscript";
-        }
-        else
-        {
-            sb << getText(decl->getName());
-        }
-    }
-
-    void SemanticsVisitor::formatDeclPath(StringBuilder& sb, DeclRef<Decl> declRef)
-    {
-        // Find the parent declaration
-        auto parentDeclRef = declRef.getParent();
-
-        // If the immediate parent is a generic, then we probably
-        // want the declaration above that...
-        auto parentGenericDeclRef = parentDeclRef.as<GenericDecl>();
-        if(parentGenericDeclRef)
-        {
-            parentDeclRef = parentGenericDeclRef.getParent();
-        }
-
-        // Depending on what the parent is, we may want to format things specially
-        if(auto aggTypeDeclRef = parentDeclRef.as<AggTypeDecl>())
-        {
-            formatDeclPath(sb, aggTypeDeclRef);
-            sb << ".";
-        }
-
-        formatDeclName(sb, declRef.getDecl());
-
-        // If the parent declaration is a generic, then we need to print out its
-        // signature
-        if( parentGenericDeclRef )
-        {
-            auto genSubst = as<GenericSubstitution>(declRef.substitutions.substitutions);
-            SLANG_RELEASE_ASSERT(genSubst);
-            SLANG_RELEASE_ASSERT(genSubst->genericDecl == parentGenericDeclRef.getDecl());
-
-            // If the name we printed previously was an operator
-            // that ends with `<`, then immediately printing the
-            // generic arguments inside `<...>` may cause it to
-            // be hard to parse the operator name visually.
-            //
-            // We thus include a space between the declaration name
-            // and its generic arguments in this case.
-            //
-            if(sb.endsWith("<")) sb << " ";
-
-            sb << "<";
-            bool first = true;
-            for(auto arg : genSubst->args)
-            {
-                // When printing the representation of a specialized
-                // generic declaration we don't want to include the
-                // argument values for subtype witnesses since these
-                // do not correspond to parameters of the generic
-                // as the user sees it.
-                //
-                if(as<Witness>(arg))
-                    continue;
-
-                if(!first) sb << ", ";
-                formatVal(sb, arg);
-                first = false;
-            }
-            sb << ">";
-        }
-    }
-
-    void SemanticsVisitor::formatDeclParams(StringBuilder& sb, DeclRef<Decl> declRef)
-    {
-        if (auto funcDeclRef = declRef.as<CallableDecl>())
-        {
-
-            // This is something callable, so we need to also print parameter types for overloading
-            sb << "(";
-
-            bool first = true;
-            for (auto paramDeclRef : getParameters(funcDeclRef))
-            {
-                if (!first) sb << ", ";
-
-                formatType(sb, getType(m_astBuilder, paramDeclRef));
-
-                first = false;
-
-            }
-
-            sb << ")";
-        }
-        else if(auto genericDeclRef = declRef.as<GenericDecl>())
-        {
-            sb << "<";
-            bool first = true;
-            for (auto paramDeclRef : getMembers(genericDeclRef))
-            {
-                if(auto genericTypeParam = paramDeclRef.as<GenericTypeParamDecl>())
-                {
-                    if (!first) sb << ", ";
-                    first = false;
-
-                    sb << getText(genericTypeParam.getName());
-                }
-                else if(auto genericValParam = paramDeclRef.as<GenericValueParamDecl>())
-                {
-                    if (!first) sb << ", ";
-                    first = false;
-
-                    sb << getText(genericValParam.getName());
-                    sb << ":";
-                    formatType(sb, getType(m_astBuilder, genericValParam));
-                }
-                else
-                {}
-            }
-            sb << ">";
-
-            formatDeclParams(sb, DeclRef<Decl>(getInner(genericDeclRef), genericDeclRef.substitutions));
-        }
-        else
-        {
-        }
-    }
-
-    static void formatDeclKindPrefix(StringBuilder& sb, Decl* decl)
-    {
-        if(auto genericDecl = as<GenericDecl>(decl))
-        {
-            decl = genericDecl->inner;
-        }
-        if(as<FuncDecl>(decl))
-        {
-            sb << "func ";
-        }
-    }
-
-    void SemanticsVisitor::formatDeclResultType(StringBuilder& sb, DeclRef<Decl> const& inDeclRef)
-    {
-        DeclRef<Decl> declRef = inDeclRef;
-        if(auto genericDeclRef = declRef.as<GenericDecl>())
-        {
-            declRef = DeclRef<Decl>(getInner(genericDeclRef), genericDeclRef.substitutions);
-        }
-
-        if(as<ConstructorDecl>(declRef))
-        {}
-        else if(auto callableDeclRef = declRef.as<CallableDecl>())
-        {
-            sb << " -> ";
-            formatType(sb, getResultType(m_astBuilder, callableDeclRef));
-        }
-    }
-
-    void SemanticsVisitor::formatDeclSignature(StringBuilder& sb, DeclRef<Decl> declRef)
-    {
-        formatDeclKindPrefix(sb, declRef.getDecl());
-        formatDeclPath(sb, declRef);
-        formatDeclParams(sb, declRef);
-        formatDeclResultType(sb, declRef);
-    }
-
-    String SemanticsVisitor::getDeclSignatureString(DeclRef<Decl> declRef)
-    {
-        StringBuilder sb;
-        formatDeclSignature(sb, declRef);
-        return sb.ProduceString();
-    }
-
-    String SemanticsVisitor::getDeclSignatureString(LookupResultItem item)
-    {
-        return getDeclSignatureString(item.declRef);
-    }
-
     String SemanticsVisitor::getCallSignatureString(
         OverloadResolveContext&     context)
     {
@@ -1469,7 +1279,7 @@ namespace Slang
         for( UInt aa = 0; aa < argCount; ++aa )
         {
             if(aa != 0) argsListBuilder << ", ";
-            argsListBuilder << context.getArgType(aa)->toString();
+            context.getArgType(aa)->toText(argsListBuilder);
         }
         argsListBuilder << ")";
         return argsListBuilder.ProduceString();
@@ -1632,7 +1442,7 @@ namespace Slang
                 Index candidateIndex = 0;
                 for (auto candidate : context.bestCandidates)
                 {
-                    String declString = getDeclSignatureString(candidate.item);
+                    String declString = ASTPrinter::getDeclSignatureString(candidate.item, m_astBuilder);
 
 //                        declString = declString + "[" + String(candidate.conversionCostSum) + "]";