From 5bcb342962634e9c36fe399a822e685bb2eb8d76 Mon Sep 17 00:00:00 2001
From: jsmall-nvidia <jsmall@nvidia.com>
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>

* 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/doc/doc.slang | 67 +++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 52 insertions(+), 15 deletions(-)

(limited to 'tests/doc')

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<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
     /// 
     /// ```
@@ -14,9 +59,12 @@ RWStructuredBuffer<int> 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<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;
-}
 
 [numthreads(4, 1, 1)]
 void computeMain(uint3 dispatchThreadID : SV_DispatchThreadID)
-- 
cgit v1.2.3