Overhaul docgen tool and setup CI to generate stdlib reference.

Author: csyonghe

.github/workflows/release.yml

@@ -194,3 +194,21 @@ jobs:
             ${{ steps.notarize.outputs.SLANG_NOTARIZED_DIST }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Checkout stdlib reference
+        if: matrix.os == 'windows' && matrix.platform == 'x86_64'
+        uses: actions/checkout@v3
+        with:
+          repository: shader-slang/stdlib-reference
+          path: docs/stdlib-reference/
+          token: ${{ secrets.UPDATE_STDLIB_REFERENCE_PAT }}
+      - name: Update stdlib reference
+        if: matrix.os == 'windows' && matrix.platform == 'x86_64'
+        shell: powershell
+        run: |
+          cd docs/
+          ls
+          & ".\build_reference.ps1"
+        env:
+          GITHUB_TOKEN: ${{ secrets.UPDATE_STDLIB_REFERENCE_PAT }}
+

.gitignore

@@ -67,6 +67,7 @@ prelude/*.h.cpp
 /docs/_site
 /docs/Gemfile.lock
 /docs/Gemfile
+/docs/stdlib-reference
 /source/slang/slang-stdlib-generated.h
 
 /examples/heterogeneous-hello-world/shader.cpp

docs/build_reference.ps1

@@ -0,0 +1,23 @@
+# If stdlib-reference folder does not exist, clone from github repo
+if (-not (Test-Path ".\stdlib-reference")) {
+    git clone https://github.com/shader-slang/stdlib-reference/
+}
+else {
+    cd stdlib-reference
+    git pull
+    cd ../
+}
+Remove-Item -Path ".\stdlib-reference\global-decls" -Recurse -Force
+Remove-Item -Path ".\stdlib-reference\interfaces" -Recurse -Force
+Remove-Item -Path ".\stdlib-reference\types" -Recurse -Force
+
+cd stdlib-reference
+& ../../build/Release/bin/slangc -compile-stdlib -doc
+Move-Item -Path ".\toc.html" -Destination ".\_includes\stdlib-reference-toc.html" -Force
+git config user.email "bot@shader-slang.com"
+git config user.name "Stdlib Reference Bot"
+git add .
+git commit -m "Update stdlib reference"
+git push
+cd ../
+

source/slang/core.meta.slang

@@ -446,6 +446,7 @@ interface IRWArray<T> : IArray<T>
 // argument. The left-to-right evaluation order guaranteed by Slang then ensures that
 // `left` is evaluated before `right`.
 //
+//@hidden:
 __generic<T,U>
 [__unsafeForceInlineEarly]
 U operator,(T left, U right)
@@ -457,20 +458,29 @@ U operator,(T left, U right)
 // follow that definition for the scalar condition overload, so this declaration just serves
 // for type-checking purpose only.
 
-__generic<T> __intrinsic_op(select) T operator?:(bool condition, T ifTrue, T ifFalse);
+//@hidden:
+__generic<T> __intrinsic_op(select) T operator?: (bool condition, T ifTrue, T ifFalse);
+
+//@hidden:
 __generic<T, let N : int> __intrinsic_op(select) vector<T,N> operator?:(vector<bool,N> condition, vector<T,N> ifTrue, vector<T,N> ifFalse);
 
 // Users are advised to use `select` instead if non-short-circuiting behavior is intended.
+//@public:
 __generic<T> __intrinsic_op(select) T select(bool condition, T ifTrue, T ifFalse);
 __generic<T, let N : int> __intrinsic_op(select) vector<T,N> select(vector<bool,N> condition, vector<T,N> ifTrue, vector<T,N> ifFalse);
 
 // Allow real-number types to be cast into each other
+//@hidden:
 __intrinsic_op($(kIROp_FloatCast))
     T __realCast<T : __BuiltinRealType, U : __BuiltinRealType>(U val);
+//@hidden:
 __intrinsic_op($(kIROp_CastIntToFloat))
-    T __realCast<T : __BuiltinRealType, U : __BuiltinIntegerType>(U val);
+T __realCast<T : __BuiltinRealType, U : __BuiltinIntegerType>(U val);
+//@hidden:
 __intrinsic_op($(kIROp_IntCast))
-    T __intCast<T : __BuiltinType, U : __BuiltinType>(U val);
+T __intCast<T : __BuiltinType, U : __BuiltinType>(U val);
+
+//@hidden:
 ${{{{
 // We are going to use code generation to produce the
 // declarations for all of our base types.
@@ -716,17 +726,20 @@ ${{{{
 // (eventually we can have the traditional syntax sugar for this)
 }}}}
 
+//@hidden:
 __magic_type(NullPtrType)
 struct NullPtr
 {
 };
 
+//@hidden:
 __magic_type(NoneType)
 __intrinsic_type($(kIROp_VoidType))
 struct __none_t
 {
 };
 
+//@public:
 __generic<T, let addrSpace : uint64_t = $( (uint64_t)AddressSpace::UserPointer)ULL>
 __magic_type(PtrType)
 __intrinsic_type($(kIROp_PtrType))
@@ -752,6 +765,7 @@ struct Ptr
     }
 };
 
+//@hidden:
 __intrinsic_op($(kIROp_Load))
 T __load<T, let addrSpace : uint64_t>(Ptr<T, addrSpace> ptr);
 
@@ -788,6 +802,7 @@ __generic<T, let addrSpace : uint64_t>
 __intrinsic_op($(kIROp_Eql))
 bool operator ==(Ptr<T, addrSpace> p1, Ptr<T, addrSpace> p2);
 
+//@public:
 extension bool : IRangedValue
 {
     __generic<T, let addrSpace : uint64_t>
@@ -847,6 +862,7 @@ extension uintptr_t : IRangedValue
     static const int size = $(SLANG_PROCESSOR_X86_64?"8":"4");
 }
 
+//@hidden:
 __generic<T>
 __magic_type(OutType)
 __intrinsic_type($(kIROp_OutType))
@@ -873,6 +889,7 @@ struct ConstRef
 
 typealias __Addr<T> = Ptr<T, $( (uint64_t)AddressSpace::Generic)ULL>;
 
+//@public:
 __generic<T>
 __magic_type(OptionalType)
 __intrinsic_type($(kIROp_OptionalType))
@@ -895,6 +912,7 @@ struct Optional
     __init(T val);
 };
 
+//@hidden:
 __generic<T>
 [__unsafeForceInlineEarly]
 bool operator==(Optional<T> val, __none_t noneVal)
@@ -920,6 +938,7 @@ bool operator!=(__none_t noneVal, Optional<T> val)
     return val.hasValue;
 }
 
+//@public:
 __generic<each T>
 __magic_type(TupleType)
 struct Tuple
@@ -936,7 +955,7 @@ Tuple<T, U> concat<each T, each U>(Tuple<T> t, Tuple<U> u)
     return makeTuple(expand each t, expand each u);
 }
 
-
+//@hidden:
 [__unsafeForceInlineEarly]
 bool __assign(inout bool v, bool newVal)
 {
@@ -978,6 +997,7 @@ void __tupleGreaterKernel<T : IComparable>(inout bool result, inout bool exit, T
     }
 }
 
+//@public:
 __generic<each T : IComparable>
 extension Tuple<T> : IComparable
 {
@@ -1027,6 +1047,7 @@ interface IDifferentiableFunc<TR : IDifferentiable, each TP : IDifferentiable> :
     TR operator()(expand each TP p);
 }
 
+//@hidden:
 __generic<T>
 __magic_type(NativeRefType)
 __intrinsic_type($(kIROp_NativePtrType))
@@ -1049,6 +1070,7 @@ T __attachToNativeRef(NativeRef<T> nativeVal)
     return result;
 }
 
+//@public:
 __magic_type(StringType)
 __intrinsic_type($(kIROp_StringType))
 struct String
@@ -1133,11 +1155,14 @@ extension Ptr<void>
     __init(NativeRef<T> ptr);
 }
 
+//@hidden:
 __magic_type(DynamicType)
 __intrinsic_type($(kIROp_DynamicType))
 struct __Dynamic
 {};
 
+//@public:
+
 extension half : IRangedValue
 {
     static const half maxValue = half(65504);
@@ -1225,9 +1250,11 @@ struct vector : IRWArray<T>
     int getCount() { return N; }
 }
 
-const int kRowMajorMatrixLayout = $(SLANG_MATRIX_LAYOUT_ROW_MAJOR);
-const int kColumnMajorMatrixLayout = $(SLANG_MATRIX_LAYOUT_COLUMN_MAJOR);
+//@hidden:
+static const int kRowMajorMatrixLayout = $(SLANG_MATRIX_LAYOUT_ROW_MAJOR);
+static const int kColumnMajorMatrixLayout = $(SLANG_MATRIX_LAYOUT_COLUMN_MAJOR);
 
+//@public:
     /// A matrix with `R` rows and `C` columns, with elements of type `T`.
 __generic<T = float, let R : int = 4, let C : int = 4, let L : int = $(SLANG_MATRIX_LAYOUT_MODE_UNKNOWN)>
 __magic_type(MatrixExpressionType)
@@ -1248,9 +1275,11 @@ struct matrix : IRWArray<vector<T,C>>
     int getCount() { return R; }
 }
 
+//@hidden:
 __intrinsic_op($(kIROp_Eql))
-vector<bool, N> __vectorEql<T, let N:int>(vector<T, N> left, vector<T,N> right);
+vector<bool, N> __vectorEql<T, let N : int>(vector<T, N> left, vector<T, N> right);
 
+//@public:
 __generic<T:__BuiltinFloatingPointType, let N : int>
 extension vector<T,N> : IFloat
 {
@@ -1360,10 +1389,12 @@ extension matrix<int16_t,R,C,L>
     __init(int value) { this = matrix<T,R,C,L>(T(value)); }
 }
 
+//@hidden:
 __intrinsic_op(makeVector)
 __generic<T, let N:int>
 vector<T,N*2> __makeVector(vector<T,N> vec1, vector<T,N> vec2);
 
+//@public:
 __generic<T>
 extension vector<T, 4>
 {
@@ -1385,6 +1416,7 @@ extension matrix<T, 2, 2, L>
     }
 }
 
+//@hidden:
 ${{{{
 static const struct {
     char const* name;
@@ -1573,7 +1605,7 @@ struct OutputPrimitives
     }
 };
 
-//@ hidden:
+//@ public:
 
 // Need to add constructors to the types above
 
@@ -1757,6 +1789,7 @@ ${{{{
 }
 }}}}
 
+//@ hidden:
 __generic<T, U>
 __intrinsic_op(0)
 T __slang_noop_cast(U u);
@@ -2267,6 +2300,8 @@ int __SyntaxError()
     }
 }
 
+//@ hidden:
+
 /// For downstream compilers that allow sizeof/alignof/offsetof
 /// Can't be called in the C/C++ style. Need to use __size_of<some_type>() as opposed to sizeof(some_type).
 __generic<T>
@@ -2350,7 +2385,7 @@ __generic<E : __EnumType>
 __intrinsic_op($(kIROp_Neq))
 bool operator!=(E left, E right);
 
-//@ public:
+//@ hidden:
 
 // public interfaces for generic arithmetic types.
 
@@ -2722,6 +2757,7 @@ __Addr<T> __getLegalizedSPIRVGlobalParamAddr(T val);
 __intrinsic_op($(kIROp_RequireComputeDerivative))
 void __requireComputeDerivative();
 
+//@ public:
 // Atomic<T>
 
 enum MemoryOrder
@@ -2767,6 +2803,7 @@ struct Atomic<T : IAtomicable>
         MemoryOrder failOrder = MemoryOrder.Relaxed);
 }
 
+/// These addtional members are only available when `T` conforms to `IArithmeticAtomicable`.
 extension<T : IArithmeticAtomicable> Atomic<T>
 {
     __intrinsic_op($(kIROp_AtomicAdd))
@@ -2779,6 +2816,7 @@ extension<T : IArithmeticAtomicable> Atomic<T>
     [__ref] T min(T value, MemoryOrder order = MemoryOrder.Relaxed); // returns original value
 }
 
+/// These addtional members are only available when `T` conforms to `IBitAtomicable`.
 extension<T : IBitAtomicable> Atomic<T>
 {
     __intrinsic_op($(kIROp_AtomicAnd))
@@ -2793,6 +2831,8 @@ extension<T : IBitAtomicable> Atomic<T>
     [__ref] T decrement(MemoryOrder order = MemoryOrder.Relaxed);
 }
 
+//@ hidden:
+
 __generic<T : IArithmeticAtomicable>
 [ForceInline]
 T operator +=(__ref Atomic<T> v, T value)