stdlib documentation (#1745)

* #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.

* Split up slang-doc into extractor and writer.

* WIP generic support for doc support.

* Some refactoring to make DocExtractor have potential to be used without Decls.

* Made doc extraction work without Decls.

* Output generic parameters.

* Add generic parameter extraction.

* Added writing variables.

* Add an interface test.

* Fix toArray.

* Support for extensions, and inheritance.

* Disable the doc test.

* Added flags to compileStdLib.

* More work around handling generics in markdown output.

* More improvements around associated type handling.

* List method names only once.
Output in/out/inout/const

* Fix namespace printing.

* WIP summarizing doc output.

* Small fixes and improvements for doc output.

* Output all stdlib in single doc file.

* Remove compile flags from addBuiltinSource.

* Find only unique signatures.
First pass at trying to get requirements.

* First pass at requirements for stdlib docs.

* Remove __ function/methods

* Added Target Availability

* Add markup access.
Make sections of stdlib hidden.

* MarkdownAccess -> Visibility
Add isVisible methods
Use ASTPrinter to print decl name.

* Add current stdlib doc output.

* Disable doc test for now.

* Fix clang issue.

* Don't use bullets and numbering , just use numbering.

* Put methods in source order.

* Fix bad-operator-call.slang test that fails because it now outputs out parameters as such.

* Refactor MarkDownWriter to separate 'extraction' from output.

* Fix typo around @ lines.

* Fix issue with extracting 'before' when preceeded by complex attributes/modifiers.

* Fix handling of generics with the same name.

* Work around for having overloading with generics - we don't want to output generic params as part of name.

* Remove generic paramters from name.

* Simplify handling of outputting overridable names.

2 files changed, 90 insertions, 53 deletions

diff --git a/tests/diagnostics/bad-operator-call.slang.expected b/tests/diagnostics/bad-operator-call.slang.expected
index 1dd52587c..6b8f250d3 100644
--- a/tests/diagnostics/bad-operator-call.slang.expected
+++ b/tests/diagnostics/bad-operator-call.slang.expected
@@ -3,36 +3,36 @@ standard error = {
 tests/diagnostics/bad-operator-call.slang(18): error 39999: no overload for '+=' applicable to arguments of type (int, S)
     a += b;
       ^~
-core.meta.slang(1904): note 39999: candidate: func +=<T, R:int, C:int>(matrix<T,R,C>, T) -> matrix<T,R,C>
-core.meta.slang(1896): note 39999: candidate: func +=<T, R:int, C:int>(matrix<T,R,C>, matrix<T,R,C>) -> matrix<T,R,C>
-core.meta.slang(1888): note 39999: candidate: func +=<T, N:int>(vector<T,N>, T) -> vector<T,N>
-core.meta.slang(1880): note 39999: candidate: func +=<T, N:int>(vector<T,N>, vector<T,N>) -> vector<T,N>
-core.meta.slang(1872): note 39999: candidate: func +=<T>(T, T) -> T
+core.meta.slang(1937): note 39999: candidate: func +=<T, R:int, C:int>(out matrix<T,R,C>, T) -> matrix<T,R,C>
+core.meta.slang(1929): note 39999: candidate: func +=<T, R:int, C:int>(out matrix<T,R,C>, matrix<T,R,C>) -> matrix<T,R,C>
+core.meta.slang(1921): note 39999: candidate: func +=<T, N:int>(out vector<T,N>, T) -> vector<T,N>
+core.meta.slang(1913): note 39999: candidate: func +=<T, N:int>(out vector<T,N>, vector<T,N>) -> vector<T,N>
+core.meta.slang(1905): note 39999: candidate: func +=<T>(out T, T) -> T
 tests/diagnostics/bad-operator-call.slang(20): error 39999: no overload for '+' applicable to arguments of type (int, S)
     a = a + b;
           ^
-core.meta.slang(1710): note 39999: candidate: func +(uint64_t, uint64_t) -> uint64_t
-core.meta.slang(1703): note 39999: candidate: func +(uint, uint) -> uint
-core.meta.slang(1696): note 39999: candidate: func +(uint16_t, uint16_t) -> uint16_t
-core.meta.slang(1689): note 39999: candidate: func +(uint8_t, uint8_t) -> uint8_t
-core.meta.slang(1682): note 39999: candidate: func +(double, double) -> double
-core.meta.slang(1675): note 39999: candidate: func +(float, float) -> float
-core.meta.slang(1668): note 39999: candidate: func +(half, half) -> half
-core.meta.slang(1661): note 39999: candidate: func +(int64_t, int64_t) -> int64_t
-core.meta.slang(1654): note 39999: candidate: func +(int, int) -> int
-core.meta.slang(1647): note 39999: candidate: func +(int16_t, int16_t) -> int16_t
+core.meta.slang(1743): note 39999: candidate: func +(uint64_t, uint64_t) -> uint64_t
+core.meta.slang(1736): note 39999: candidate: func +(uint, uint) -> uint
+core.meta.slang(1729): note 39999: candidate: func +(uint16_t, uint16_t) -> uint16_t
+core.meta.slang(1722): note 39999: candidate: func +(uint8_t, uint8_t) -> uint8_t
+core.meta.slang(1715): note 39999: candidate: func +(double, double) -> double
+core.meta.slang(1708): note 39999: candidate: func +(float, float) -> float
+core.meta.slang(1701): note 39999: candidate: func +(half, half) -> half
+core.meta.slang(1694): note 39999: candidate: func +(int64_t, int64_t) -> int64_t
+core.meta.slang(1687): note 39999: candidate: func +(int, int) -> int
+core.meta.slang(1680): note 39999: candidate: func +(int16_t, int16_t) -> int16_t
 tests/diagnostics/bad-operator-call.slang(20): note 39999: 1 more overload candidates
 tests/diagnostics/bad-operator-call.slang(22): error 39999: no overload for '~' applicable to arguments of type (S)
     a = ~b;
         ^
-slang-stdlib.cpp(1718): note 39999: candidate: func ~(uint64_t) -> uint64_t
-slang-stdlib.cpp(1715): note 39999: candidate: func ~(uint) -> uint
-slang-stdlib.cpp(1712): note 39999: candidate: func ~(uint16_t) -> uint16_t
-slang-stdlib.cpp(1709): note 39999: candidate: func ~(uint8_t) -> uint8_t
-slang-stdlib.cpp(1706): note 39999: candidate: func ~(int64_t) -> int64_t
-slang-stdlib.cpp(1703): note 39999: candidate: func ~(int) -> int
-slang-stdlib.cpp(1700): note 39999: candidate: func ~(int16_t) -> int16_t
-slang-stdlib.cpp(1697): note 39999: candidate: func ~(int8_t) -> int8_t
+core.meta.slang(1629): note 39999: candidate: func ~(uint64_t) -> uint64_t
+core.meta.slang(1626): note 39999: candidate: func ~(uint) -> uint
+core.meta.slang(1623): note 39999: candidate: func ~(uint16_t) -> uint16_t
+core.meta.slang(1620): note 39999: candidate: func ~(uint8_t) -> uint8_t
+core.meta.slang(1617): note 39999: candidate: func ~(int64_t) -> int64_t
+core.meta.slang(1614): note 39999: candidate: func ~(int) -> int
+core.meta.slang(1611): note 39999: candidate: func ~(int16_t) -> int16_t
+core.meta.slang(1608): note 39999: candidate: func ~(int8_t) -> int8_t
 tests/diagnostics/bad-operator-call.slang(27): error 30047: argument passed to parameter '0' must be l-value.
     a += c;
     ^
@@ -40,24 +40,24 @@ tests/diagnostics/bad-operator-call.slang(27): note 30048: argument was implicit
 tests/diagnostics/bad-operator-call.slang(31): error 39999: no overload for '+=' applicable to arguments of type (vector<float,3>, vector<int,4>)
     d += c;
       ^~
-core.meta.slang(1904): note 39999: candidate: func +=<T, R:int, C:int>(matrix<T,R,C>, T) -> matrix<T,R,C>
-core.meta.slang(1896): note 39999: candidate: func +=<T, R:int, C:int>(matrix<T,R,C>, matrix<T,R,C>) -> matrix<T,R,C>
-core.meta.slang(1888): note 39999: candidate: func +=<T, N:int>(vector<T,N>, T) -> vector<T,N>
-core.meta.slang(1880): note 39999: candidate: func +=<T, N:int>(vector<T,N>, vector<T,N>) -> vector<T,N>
-core.meta.slang(1872): note 39999: candidate: func +=<T>(T, T) -> T
+core.meta.slang(1937): note 39999: candidate: func +=<T, R:int, C:int>(out matrix<T,R,C>, T) -> matrix<T,R,C>
+core.meta.slang(1929): note 39999: candidate: func +=<T, R:int, C:int>(out matrix<T,R,C>, matrix<T,R,C>) -> matrix<T,R,C>
+core.meta.slang(1921): note 39999: candidate: func +=<T, N:int>(out vector<T,N>, T) -> vector<T,N>
+core.meta.slang(1913): note 39999: candidate: func +=<T, N:int>(out vector<T,N>, vector<T,N>) -> vector<T,N>
+core.meta.slang(1905): note 39999: candidate: func +=<T>(out T, T) -> T
 tests/diagnostics/bad-operator-call.slang(33): error 39999: no overload for '+' applicable to arguments of type (vector<int,4>, vector<float,3>)
     d = c + d;
           ^
-core.meta.slang(1715): note 39999: candidate: func +<4>(vector<uint64_t,4>, uint64_t) -> vector<uint64_t,4>
-core.meta.slang(1713): note 39999: candidate: func +<3>(uint64_t, vector<uint64_t,3>) -> vector<uint64_t,3>
-core.meta.slang(1710): note 39999: candidate: func +(uint64_t, uint64_t) -> uint64_t
-core.meta.slang(1708): note 39999: candidate: func +<4>(vector<uint,4>, uint) -> vector<uint,4>
-core.meta.slang(1706): note 39999: candidate: func +<3>(uint, vector<uint,3>) -> vector<uint,3>
-core.meta.slang(1703): note 39999: candidate: func +(uint, uint) -> uint
-core.meta.slang(1701): note 39999: candidate: func +<4>(vector<uint16_t,4>, uint16_t) -> vector<uint16_t,4>
-core.meta.slang(1699): note 39999: candidate: func +<3>(uint16_t, vector<uint16_t,3>) -> vector<uint16_t,3>
-core.meta.slang(1696): note 39999: candidate: func +(uint16_t, uint16_t) -> uint16_t
-core.meta.slang(1694): note 39999: candidate: func +<4>(vector<uint8_t,4>, uint8_t) -> vector<uint8_t,4>
+core.meta.slang(1748): note 39999: candidate: func +<4>(vector<uint64_t,4>, uint64_t) -> vector<uint64_t,4>
+core.meta.slang(1746): note 39999: candidate: func +<3>(uint64_t, vector<uint64_t,3>) -> vector<uint64_t,3>
+core.meta.slang(1743): note 39999: candidate: func +(uint64_t, uint64_t) -> uint64_t
+core.meta.slang(1741): note 39999: candidate: func +<4>(vector<uint,4>, uint) -> vector<uint,4>
+core.meta.slang(1739): note 39999: candidate: func +<3>(uint, vector<uint,3>) -> vector<uint,3>
+core.meta.slang(1736): note 39999: candidate: func +(uint, uint) -> uint
+core.meta.slang(1734): note 39999: candidate: func +<4>(vector<uint16_t,4>, uint16_t) -> vector<uint16_t,4>
+core.meta.slang(1732): note 39999: candidate: func +<3>(uint16_t, vector<uint16_t,3>) -> vector<uint16_t,3>
+core.meta.slang(1729): note 39999: candidate: func +(uint16_t, uint16_t) -> uint16_t
+core.meta.slang(1727): note 39999: candidate: func +<4>(vector<uint8_t,4>, uint8_t) -> vector<uint8_t,4>
 tests/diagnostics/bad-operator-call.slang(33): note 39999: 23 more overload candidates
 }
 standard output = {
diff --git a/tests/doc/doc.slang b/tests/doc/doc.slang
index b983011c5..447b6f6f3 100644
--- a/tests/doc/doc.slang
+++ b/tests/doc/doc.slang
@@ -1,5 +1,50 @@
 //DISABLE_TEST:SIMPLE:-entry computeMain -target spirv -stage compute -doc
 
+void outFunc(out int v)
+{
+    v = 10;
+}
+
+/// Testing out nested generics
+struct ParentStruct<T> ///< Some type
+{
+    /// Testing out a child
+    struct ChildStruct<S> ///< Some other type
+    {
+        /// A useless method hey ho
+        T getValue(S v) { T t; S s; return t; }
+    };
+};
+
+struct GenericStruct<T>
+{
+        /// Let's try a typedef too
+    typedef T Element;
+
+    T getValue() { return value; }
+    
+    T value;
+};
+
+/// A rather silly generic function to test out doc extraction
+T addInts<T : __BuiltinIntegerType,     ///< The type we are operating on 
+    /// Just testing out a 
+    /// non type based generic
+    let U : int,
+    let V : int>    ///< And another one                       
+    (
+    /// CHECKING!!
+    T z,           ///< The Z parameter
+    T b)            ///< The B parameter
+{
+    return z + b;
+}
+
+namespace Hey
+{
+    void doAnotherThing(int a);
+}
+
     /// Let's test indent
     /// 
     /// ```
@@ -14,9 +59,12 @@ RWStructuredBuffer<int> inputBuffer;
 /// An interface to do things
 interface IDoThing
 {
+        /// An associated type
+    associatedtype V;
+    
         /// Add two integers
-    int add(int a,      ///< First parameter 
-        int b           ///< Second parameter
+    V add(V a,      ///< First parameter 
+        V b           ///< Second parameter
     );
     
         /// Subtract
@@ -40,6 +88,8 @@ extension float : IThing
 
 struct Thing : IThing, IDoThing
 {
+    typedef int V;
+    
     int add(int a, int b) { return a + b; }
     int sub(int a, int b ) { return a - b; }
     float getValue() { return 1.0f; }
@@ -86,19 +136,6 @@ int doThing(int a,  ///< a parameter
     return a;
 }
 
-/// A rather silly generic function to test out doc extraction
-T addInts<T : __BuiltinIntegerType,     ///< The type we are operating on 
-    /// Just testing out a 
-    /// non type based generic
-    let U : int,
-    let V : int>    ///< And another one                       
-    (
-    /// CHECKING!!
-    T z,           ///< The Z parameter
-    T b)            ///< The B parameter
-{
-    return z + b;
-}
 
 [numthreads(4, 1, 1)]
 void computeMain(uint3 dispatchThreadID : SV_DispatchThreadID)