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.

1 files changed, 30 insertions, 10 deletions

diff --git a/source/slang/core.meta.slang b/source/slang/core.meta.slang
index 39ee702c6..6b20dbc3b 100644
--- a/source/slang/core.meta.slang
+++ b/source/slang/core.meta.slang
@@ -27,12 +27,12 @@ syntax globallycoherent : GloballyCoherentModifier;
 ///
 syntax pervertex : PerVertexModifier;
 
-// A type that can be used as an operand for builtins
+/// A type that can be used as an operand for builtins
 [sealed]
 [builtin]
 interface __BuiltinType {}
 
-// A type that can be used for arithmetic operations
+/// A type that can be used for arithmetic operations
 [sealed]
 [builtin]
 interface __BuiltinArithmeticType : __BuiltinType
@@ -41,28 +41,28 @@ interface __BuiltinArithmeticType : __BuiltinType
     __init(int value);
 }
 
-    /// A type that can be used for logical/bitwsie operations
+/// A type that can be used for logical/bitwise operations
 [sealed]
 [builtin]
 interface __BuiltinLogicalType : __BuiltinType {}
 
-// A type that logically has a sign (positive/negative/zero)
+/// A type that logically has a sign (positive/negative/zero)
 [sealed]
 [builtin]
 interface __BuiltinSignedArithmeticType : __BuiltinArithmeticType {}
 
-// A type that can represent integers
+/// A type that can represent integers
 [sealed]
 [builtin]
 interface __BuiltinIntegerType : __BuiltinArithmeticType
 {}
 
-// A type that can represent non-integers
+/// A type that can represent non-integers
 [sealed]
 [builtin]
 interface __BuiltinRealType : __BuiltinSignedArithmeticType {}
 
-// A type that uses a floating-point representation
+/// A type that uses a floating-point representation
 [sealed]
 [builtin]
 interface __BuiltinFloatingPointType : __BuiltinRealType
@@ -74,6 +74,8 @@ interface __BuiltinFloatingPointType : __BuiltinRealType
     static This getPi();
 }
 
+//@ hidden:
+
 // A type resulting from an `enum` declaration.
 [builtin]
 __magic_type(EnumTypeType)
@@ -406,6 +408,8 @@ for (int tt = 0; tt < kTypeCount; ++tt)
 // Declare additional built-in generic types
 }}}}
 
+//@ public:
+
 __generic<T>
 __intrinsic_type($(kIROp_ConstantBufferType))
 __magic_type(ConstantBuffer)
@@ -421,6 +425,8 @@ __intrinsic_type($(kIROp_ParameterBlockType))
 __magic_type(ParameterBlockType)
 struct ParameterBlock {}
 
+//@ hidden:
+
 ${{{{
 
 static const char* kComponentNames[]{ "x", "y", "z", "w" };
@@ -575,6 +581,8 @@ ${{{{
 }}}}
 
 
+//@ public:
+
     /// Sampling state for filtered texture fetches.
 __magic_type(SamplerState, $(int(SamplerStateFlavor::SamplerState)))
 __intrinsic_type($(kIROp_SamplerStateType))
@@ -1554,6 +1562,11 @@ for (int tt = 0; tt < kBaseTextureTypeCount; ++tt)
     }
 }
 
+}}}}
+
+//@ hidden:
+
+${{{{
 
 for (auto op : intrinsicUnaryOps)
 {
@@ -1933,6 +1946,8 @@ ${{{{
 
 }}}}
 
+//@ public:
+
 // Bit cast
 __generic<T, U>
 [__unsafeForceInlineEarly]
@@ -1941,12 +1956,13 @@ T bit_cast(U value);
 
 // Specialized function
 
+/// Given a string returns an integer hash of that string.
 __intrinsic_op
 int getStringHash(String string);
 
-// Use will produce a syntax error in downstream compiler
-// Useful for testing diagnostics around compilation errors of downstream compiler
-// It 'returns' an int so can be used in expressions without the front end complaining.
+/// Use will produce a syntax error in downstream compiler
+/// Useful for testing diagnostics around compilation errors of downstream compiler
+/// It 'returns' an int so can be used in expressions without the front end complaining.
 __target_intrinsic(hlsl, " @ ")
 __target_intrinsic(glsl, " @ ")
 __target_intrinsic(cuda, " @ ")
@@ -1967,6 +1983,8 @@ void endInvocationInterlock() {}
 
 // Operators to apply to `enum` types
 
+//@ hidden:
+
 __generic<E : __EnumType>
 __intrinsic_op($(kIROp_Eql))
 bool operator==(E left, E right);
@@ -1975,6 +1993,8 @@ __generic<E : __EnumType>
 __intrinsic_op($(kIROp_Neq))
 bool operator!=(E left, E right);
 
+//@ public:
+
 // Binding Attributes
 
 __attributeTarget(DeclBase)