From 5bcb342962634e9c36fe399a822e685bb2eb8d76 Mon Sep 17 00:00:00 2001 From: jsmall-nvidia Date: Thu, 11 Mar 2021 17:08:08 -0500 Subject: 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 -> 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. --- source/slang/core.meta.slang | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) (limited to 'source/slang/core.meta.slang') 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 __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 [__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 __intrinsic_op($(kIROp_Eql)) bool operator==(E left, E right); @@ -1975,6 +1993,8 @@ __generic __intrinsic_op($(kIROp_Neq)) bool operator!=(E left, E right); +//@ public: + // Binding Attributes __attributeTarget(DeclBase) -- cgit v1.2.3