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. --- tests/diagnostics/bad-operator-call.slang.expected | 76 +++++++++++----------- tests/doc/doc.slang | 67 ++++++++++++++----- 2 files changed, 90 insertions(+), 53 deletions(-) (limited to 'tests') 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 +=(matrix, T) -> matrix -core.meta.slang(1896): note 39999: candidate: func +=(matrix, matrix) -> matrix -core.meta.slang(1888): note 39999: candidate: func +=(vector, T) -> vector -core.meta.slang(1880): note 39999: candidate: func +=(vector, vector) -> vector -core.meta.slang(1872): note 39999: candidate: func +=(T, T) -> T +core.meta.slang(1937): note 39999: candidate: func +=(out matrix, T) -> matrix +core.meta.slang(1929): note 39999: candidate: func +=(out matrix, matrix) -> matrix +core.meta.slang(1921): note 39999: candidate: func +=(out vector, T) -> vector +core.meta.slang(1913): note 39999: candidate: func +=(out vector, vector) -> vector +core.meta.slang(1905): note 39999: candidate: func +=(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, vector) d += c; ^~ -core.meta.slang(1904): note 39999: candidate: func +=(matrix, T) -> matrix -core.meta.slang(1896): note 39999: candidate: func +=(matrix, matrix) -> matrix -core.meta.slang(1888): note 39999: candidate: func +=(vector, T) -> vector -core.meta.slang(1880): note 39999: candidate: func +=(vector, vector) -> vector -core.meta.slang(1872): note 39999: candidate: func +=(T, T) -> T +core.meta.slang(1937): note 39999: candidate: func +=(out matrix, T) -> matrix +core.meta.slang(1929): note 39999: candidate: func +=(out matrix, matrix) -> matrix +core.meta.slang(1921): note 39999: candidate: func +=(out vector, T) -> vector +core.meta.slang(1913): note 39999: candidate: func +=(out vector, vector) -> vector +core.meta.slang(1905): note 39999: candidate: func +=(out T, T) -> T tests/diagnostics/bad-operator-call.slang(33): error 39999: no overload for '+' applicable to arguments of type (vector, vector) d = c + d; ^ -core.meta.slang(1715): note 39999: candidate: func +<4>(vector, uint64_t) -> vector -core.meta.slang(1713): note 39999: candidate: func +<3>(uint64_t, vector) -> vector -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) -> vector -core.meta.slang(1706): note 39999: candidate: func +<3>(uint, vector) -> vector -core.meta.slang(1703): note 39999: candidate: func +(uint, uint) -> uint -core.meta.slang(1701): note 39999: candidate: func +<4>(vector, uint16_t) -> vector -core.meta.slang(1699): note 39999: candidate: func +<3>(uint16_t, vector) -> vector -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) -> vector +core.meta.slang(1748): note 39999: candidate: func +<4>(vector, uint64_t) -> vector +core.meta.slang(1746): note 39999: candidate: func +<3>(uint64_t, vector) -> vector +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) -> vector +core.meta.slang(1739): note 39999: candidate: func +<3>(uint, vector) -> vector +core.meta.slang(1736): note 39999: candidate: func +(uint, uint) -> uint +core.meta.slang(1734): note 39999: candidate: func +<4>(vector, uint16_t) -> vector +core.meta.slang(1732): note 39999: candidate: func +<3>(uint16_t, vector) -> vector +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) -> vector 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 ///< Some type +{ + /// Testing out a child + struct ChildStruct ///< Some other type + { + /// A useless method hey ho + T getValue(S v) { T t; S s; return t; } + }; +}; + +struct GenericStruct +{ + /// 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 ///< 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 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 ///< 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) -- cgit v1.2.3