Overhaul docgen tool and setup CI to generate stdlib reference. (#5232)

* Overhaul docgen tool and setup CI to generate stdlib reference.

* Fix build error.

* Write parsed doc for all decls.

* fix.

* fix callout.

* Fix.

* Fix comment.

* Fix.

* Delete obsolete doc tests.

* Fix.

* Categorize functions and types.

* Fix CI.

* Update comments.

10 files changed, 23 insertions, 594 deletions

diff --git a/tests/doc/doc-req.slang b/tests/doc/doc-req.slang
deleted file mode 100644
index bee11f7d4..000000000
--- a/tests/doc/doc-req.slang
+++ /dev/null
@@ -1,15 +0,0 @@
-//TEST:DOC:-module-name module -doc -no-codegen
-
-// To Test out documentation around intrinsics
-
-__target_intrinsic(hlsl, "someHLSLThing()")
-[__requiresNVAPI]
-__cuda_sm_version(2.0)
-__target_intrinsic(cuda, "someCUDAThing()")
-__target_intrinsic(glsl, "someGLSLThing()")
-__glsl_extension(GL_EXT_NiftyExtension)
-__spirv_version(1.3)
-__target_intrinsic(cpp, "someCPPThing()")
-void doThing()
-{
-}
diff --git a/tests/doc/doc-req.slang.expected b/tests/doc/doc-req.slang.expected
deleted file mode 100644
index 51421cdc7..000000000
--- a/tests/doc/doc-req.slang.expected
+++ /dev/null
@@ -1,18 +0,0 @@
-result code = 0
-standard error = {
---------------------------------------------------------------------------------
-# `doThing`
-
-## Signature 
-
-```
-void doThing();
-```
-
-## Availability
-
-**GLSL** `GL_EXT_NiftyExtension`, `SPIR-V 1.3` **HLSL** `NVAPI` **CPP** **CUDA** `SM 2.0` 
-
-}
-standard output = {
-}
diff --git a/tests/doc/doc.slang b/tests/doc/doc.slang
deleted file mode 100644
index e75768b9e..000000000
--- a/tests/doc/doc.slang
+++ /dev/null
@@ -1,163 +0,0 @@
-//TEST:DOC:-entry computeMain -target hlsl -stage compute -doc -no-codegen
-
-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
-    /// 
-    /// ```
-    /// {
-    ///     imIndented();
-    /// }   
-    /// ```
-    ///
-RWStructuredBuffer<int> inputBuffer;       
-
-
-/// An interface to do things
-interface IDoThing
-{
-        /// An associated type
-    associatedtype V;
-    
-        /// Add two integers
-    V add(V a,      ///< First parameter 
-        V b           ///< Second parameter
-    );
-    
-        /// Subtract
-        /// Multi-line
-    int sub(int a,      ///< First
-            int b       ///< Second
-    );
-}
-
-interface IThing
-{
-    float getValue();
-};
-
-/// Implement IThing on float
-extension float : IThing
-{
-        /// Just return the float itself!
-	float getValue() { return this; }
-}
-
-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; }
-};
-
-/// A struct with some fields
-struct SomeStruct
-{
-    /// A field
-    int aField;
-    /// Multi-line 
-    /// is a thing
-    int anotherField;
-    int yetAnother; ///< A field with stuff 
-    
-        /// Get a value 
-    int getMethod() { return yetAnother; }
-};
-
-/// An enum
-enum AnEnum
-{
-    Value, ///< A value
-    /// Another value
-    /// With a multi-line comment
-    AnotherValue,
-};
-
-
-//TEST_INPUT:ubuffer(data=[0 0 0 0], stride=4):out,name outputBuffer
-RWStructuredBuffer<int> outputBuffer;       ///< An output buffer
-
-/// doThing!
-int doThing(int a,  ///< a parameter
-            int b)  ///< b parameter
-{
-    while (b >= 0)
-    {
-        a 
-        += 
-        a;
-    }
-    
-    return a;
-}
-
-
-[numthreads(4, 1, 1)]
-void computeMain(uint3 dispatchThreadID : SV_DispatchThreadID)
-{
-    int a = int(dispatchThreadID.x);
-    int b = int(dispatchThreadID.y);
-    int c = int(dispatchThreadID.z);
-    int d = a + b * c;
-    int e = d + c / 2;
-    
-    for (int i = 0; i < b; ++i)
-    {
-        if (e > 10 && (i & 2) != 0)
-        {
-            a += b; b -= c; c += c; d = d + e + a; e = a;
-        }
-        else
-        {
-            a = e; b = c + c; d += d + __SyntaxError(); e = doThing(e, int(dispatchThreadID.x));
-            
-        }
-    }
-    
-    outputBuffer[dispatchThreadID.x] = a + b + c + d + e;
-}
diff --git a/tests/doc/doc.slang.expected b/tests/doc/doc.slang.expected
deleted file mode 100644
index 1163e6485..000000000
--- a/tests/doc/doc.slang.expected
+++ /dev/null
@@ -1,375 +0,0 @@
-result code = 0
-standard error = {
---------------------------------------------------------------------------------
-# `outFunc`
-
-## Signature 
-
-```
-void outFunc(out int v);
-```
-
-## Parameters
-
-* `v`
-
---------------------------------------------------------------------------------
-# `struct ParentStruct<T>`
-
-## Description
-
-Testing out nested generics
-
-## Generic Parameters
-
-* `T` Some type 
-
---------------------------------------------------------------------------------
-# `struct ParentStruct<T>.ChildStruct<S>`
-
-## Description
-
-Testing out a child
-
-## Generic Parameters
-
-* `S` Some other type 
-
-## Methods
-
-* `getValue`
-
---------------------------------------------------------------------------------
-# `ParentStruct<T>.ChildStruct<S>.getValue`
-
-## Description
-
-A useless method hey ho
-
-## Signature 
-
-```
-T ParentStruct<T>.ChildStruct<S>.getValue(S v);
-```
-
-## Parameters
-
-* `v`
-
---------------------------------------------------------------------------------
-# `struct GenericStruct<T>`
-
-## Generic Parameters
-
-* `T`
-
-## Fields
-
-* `value`
-
-## Methods
-
-* `getValue`
-
---------------------------------------------------------------------------------
-# `GenericStruct<T>.getValue`
-
-## Signature 
-
-```
-T GenericStruct<T>.getValue();
-```
-
---------------------------------------------------------------------------------
-# `addInts`
-
-## Description
-
-A rather silly generic function to test out doc extraction
-
-## Signature 
-
-```
-T addInts<T, U:int, V:int>(
-    T                    z,
-    T                    b);
-```
-
-## Parameters
-
-* `T` The type we are operating on  
-* `U` Just testing out a  non type based generic 
-* `V` And another one                        
-* `z` CHECKING!! 
-* `b` The B parameter 
-
---------------------------------------------------------------------------------
-# `Hey::doAnotherThing`
-
-## Signature 
-
-```
-void Hey::doAnotherThing(int a);
-```
-
-## Parameters
-
-* `a`
-
---------------------------------------------------------------------------------
-# inputBuffer
-
-```
-RWStructuredBuffer<int, DefaultDataLayout> inputBuffer
-```
-
-## Description
-
-Let's test indent
-
-```
-{
-    imIndented();
-}   
-```
-
---------------------------------------------------------------------------------
-# `interface IDoThing`
-
-## Description
-
-An interface to do things
-
-# Associated types
-
-* _V_ An associated type 
-
-
-## Methods
-
-* `add`
-* `sub`
-
---------------------------------------------------------------------------------
-# `IDoThing.add`
-
-## Description
-
-Add two integers
-
-## Signature 
-
-```
-This.V IDoThing.add(
-    This.V               a,
-    This.V               b);
-```
-
-## Parameters
-
-* `a` First parameter  
-* `b` Second parameter 
-
---------------------------------------------------------------------------------
-# `IDoThing.sub`
-
-## Description
-
-Subtract
-Multi-line
-
-## Signature 
-
-```
-int IDoThing.sub(
-    int                  a,
-    int                  b);
-```
-
-## Parameters
-
-* `a` First 
-* `b` Second 
-
---------------------------------------------------------------------------------
-# `interface IThing`
-
-## Methods
-
-* `getValue`
-
---------------------------------------------------------------------------------
-# `IThing.getValue`
-
-## Signature 
-
-```
-float IThing.getValue();
-```
-
---------------------------------------------------------------------------------
-# `extension float : IThing`
-
-*Implements:* `IThing`
-
-## Description
-
-Implement IThing on float
-
-## Methods
-
-* `getValue`
-
---------------------------------------------------------------------------------
-# `float.getValue`
-
-## Description
-
-Just return the float itself!
-
-## Signature 
-
-```
-float float.getValue();
-```
-
---------------------------------------------------------------------------------
-# `struct Thing`
-
-*Implements:* `IThing`, `IDoThing`
-
-## Methods
-
-* `add`
-* `sub`
-* `getValue`
-
---------------------------------------------------------------------------------
-# `Thing.add`
-
-## Signature 
-
-```
-int Thing.add(
-    int                  a,
-    int                  b);
-```
-
-## Parameters
-
-* `a`
-* `b`
-
---------------------------------------------------------------------------------
-# `Thing.sub`
-
-## Signature 
-
-```
-int Thing.sub(
-    int                  a,
-    int                  b);
-```
-
-## Parameters
-
-* `a`
-* `b`
-
---------------------------------------------------------------------------------
-# `Thing.getValue`
-
-## Signature 
-
-```
-float Thing.getValue();
-```
-
---------------------------------------------------------------------------------
-# `struct SomeStruct`
-
-## Description
-
-A struct with some fields
-
-## Fields
-
-* `aField` A field 
-* `anotherField` Multi-line  is a thing 
-* `yetAnother` A field with stuff  
-
-## Methods
-
-* `getMethod`
-
---------------------------------------------------------------------------------
-# `SomeStruct.getMethod`
-
-## Description
-
-Get a value 
-
-## Signature 
-
-```
-int SomeStruct.getMethod();
-```
-
---------------------------------------------------------------------------------
-# enum AnEnum
-
-## Values 
-
-* _Value_ A value 
-* _AnotherValue_ Another value With a multi-line comment 
-## Description
-
-An enum
-
---------------------------------------------------------------------------------
-# outputBuffer
-
-```
-RWStructuredBuffer<int, DefaultDataLayout> outputBuffer
-```
-
-## Description
-
-An output buffer
-
---------------------------------------------------------------------------------
-# `doThing`
-
-## Description
-
-doThing!
-
-## Signature 
-
-```
-int doThing(
-    int                  a,
-    int                  b);
-```
-
-## Parameters
-
-* `a` a parameter 
-* `b` b parameter 
-
---------------------------------------------------------------------------------
-# `computeMain`
-
-## Signature 
-
-```
-void computeMain(vector<uint,3> dispatchThreadID);
-```
-
-## Parameters
-
-* `dispatchThreadID`
-
-}
-standard output = {
-}
diff --git a/tests/metal/texture-sampler-less.slang b/tests/metal/texture-sampler-less.slang
index 70b805ce7..188b15469 100644
--- a/tests/metal/texture-sampler-less.slang
+++ b/tests/metal/texture-sampler-less.slang
@@ -30,7 +30,7 @@ SamplerCubeArray<float> tCubeArray;
 
 // Metal doc says "For depth texture types, T must be float."
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depth2d = __TextureImpl<
+typealias depth2d = _Texture<
     T,
     __Shape2D,
     0, // isArray
@@ -43,7 +43,7 @@ typealias depth2d = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depth2d_array = __TextureImpl<
+typealias depth2d_array = _Texture<
     T,
     __Shape2D,
     1, // isArray
@@ -56,7 +56,7 @@ typealias depth2d_array = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depthcube = __TextureImpl<
+typealias depthcube = _Texture<
     T,
     __ShapeCube,
     0, // isArray
@@ -69,7 +69,7 @@ typealias depthcube = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depthcube_array = __TextureImpl<
+typealias depthcube_array = _Texture<
     T,
     __ShapeCube,
     1, // isArray
diff --git a/tests/metal/texture.slang b/tests/metal/texture.slang
index a083f2ff5..37c8fa286 100644
--- a/tests/metal/texture.slang
+++ b/tests/metal/texture.slang
@@ -122,7 +122,7 @@ TextureCubeArray<uint16_t4> tCubeArray_u16;
 
 // Metal doc says "For depth texture types, T must be float."
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depth2d = __TextureImpl<
+typealias depth2d = _Texture<
     T,
     __Shape2D,
     0, // isArray
@@ -135,7 +135,7 @@ typealias depth2d = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depth2d_array = __TextureImpl<
+typealias depth2d_array = _Texture<
     T,
     __Shape2D,
     1, // isArray
@@ -148,7 +148,7 @@ typealias depth2d_array = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depthcube = __TextureImpl<
+typealias depthcube = _Texture<
     T,
     __ShapeCube,
     0, // isArray
@@ -161,7 +161,7 @@ typealias depthcube = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depthcube_array = __TextureImpl<
+typealias depthcube_array = _Texture<
     T,
     __ShapeCube,
     1, // isArray
diff --git a/tests/wgsl/texture-gather.slang b/tests/wgsl/texture-gather.slang
index a95428a1d..b77ec9f8f 100644
--- a/tests/wgsl/texture-gather.slang
+++ b/tests/wgsl/texture-gather.slang
@@ -69,7 +69,7 @@ TextureCubeArray<uint4> tCubeArray_u32v4;
 // depth
 
 __generic<let sampleCount:int=0, let format:int=0>
-typealias Depth2D = __TextureImpl<
+typealias Depth2D = _Texture<
     float,
     __Shape2D,
     0, // isArray
@@ -82,7 +82,7 @@ typealias Depth2D = __TextureImpl<
 >;
 
 __generic<let sampleCount:int=0, let format:int=0>
-typealias Depth2DArray = __TextureImpl<
+typealias Depth2DArray = _Texture<
     float,
     __Shape2D,
     1, // isArray
@@ -95,7 +95,7 @@ typealias Depth2DArray = __TextureImpl<
 >;
 
 __generic<let sampleCount:int=0, let format:int=0>
-typealias DepthCube = __TextureImpl<
+typealias DepthCube = _Texture<
     float,
     __ShapeCube,
     0, // isArray
@@ -108,7 +108,7 @@ typealias DepthCube = __TextureImpl<
 >;
 
 __generic<let sampleCount:int=0, let format:int=0>
-typealias DepthCubeArray = __TextureImpl<
+typealias DepthCubeArray = _Texture<
     float,
     __ShapeCube,
     1, // isArray
diff --git a/tests/wgsl/texture-load.slang b/tests/wgsl/texture-load.slang
index cc49b8709..3e69ac5cf 100644
--- a/tests/wgsl/texture-load.slang
+++ b/tests/wgsl/texture-load.slang
@@ -81,7 +81,7 @@ Texture2DArray<uint4> t2DArray_u32v4;
 // depth
 
 __generic<let sampleCount:int=0, let format:int=0>
-typealias Depth2D = __TextureImpl<
+typealias Depth2D = _Texture<
     float,
     __Shape2D,
     0, // isArray
@@ -94,7 +94,7 @@ typealias Depth2D = __TextureImpl<
 >;
 
 __generic<let sampleCount:int=0, let format:int=0>
-typealias Depth2DMS = __TextureImpl<
+typealias Depth2DMS = _Texture<
     float,
     __Shape2D,
     0, // isArray
@@ -107,7 +107,7 @@ typealias Depth2DMS = __TextureImpl<
 >;
 
 __generic<let sampleCount:int=0, let format:int=0>
-typealias Depth2DArray = __TextureImpl<
+typealias Depth2DArray = _Texture<
     float,
     __Shape2D,
     1, // isArray
diff --git a/tests/wgsl/texture-sampler-less.slang b/tests/wgsl/texture-sampler-less.slang
index 893e867b7..249803526 100644
--- a/tests/wgsl/texture-sampler-less.slang
+++ b/tests/wgsl/texture-sampler-less.slang
@@ -44,7 +44,7 @@ Sampler2DArray<float4> t2DArray_f32v4;
 SamplerCubeArray<float4> tCubeArray_f32v4;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias CombinedDepth2d = __TextureImpl<
+typealias CombinedDepth2d = _Texture<
     T,
     __Shape2D,
     0, // isArray
@@ -57,7 +57,7 @@ typealias CombinedDepth2d = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias CombinedDepth2d_array = __TextureImpl<
+typealias CombinedDepth2d_array = _Texture<
     T,
     __Shape2D,
     1, // isArray
@@ -70,7 +70,7 @@ typealias CombinedDepth2d_array = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias CombinedDepthcube = __TextureImpl<
+typealias CombinedDepthcube = _Texture<
     T,
     __ShapeCube,
     0, // isArray
@@ -83,7 +83,7 @@ typealias CombinedDepthcube = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias CombinedDepthcube_array = __TextureImpl<
+typealias CombinedDepthcube_array = _Texture<
     T,
     __ShapeCube,
     1, // isArray
diff --git a/tests/wgsl/texture.slang b/tests/wgsl/texture.slang
index 49f730eeb..be098c9ca 100644
--- a/tests/wgsl/texture.slang
+++ b/tests/wgsl/texture.slang
@@ -36,7 +36,7 @@ Texture2DArray<float4> t2DArray_f32v4;
 TextureCubeArray<float4> tCubeArray_f32v4;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depth2d = __TextureImpl<
+typealias depth2d = _Texture<
     T,
     __Shape2D,
     0, // isArray
@@ -49,7 +49,7 @@ typealias depth2d = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depth2d_array = __TextureImpl<
+typealias depth2d_array = _Texture<
     T,
     __Shape2D,
     1, // isArray
@@ -62,7 +62,7 @@ typealias depth2d_array = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depthcube = __TextureImpl<
+typealias depthcube = _Texture<
     T,
     __ShapeCube,
     0, // isArray
@@ -75,7 +75,7 @@ typealias depthcube = __TextureImpl<
 >;
 
 __generic<T : __BuiltinType, let sampleCount:int=0, let format:int=0>
-typealias depthcube_array = __TextureImpl<
+typealias depthcube_array = _Texture<
     T,
     __ShapeCube,
     1, // isArray