From 16a47816747ca9a9de67b842a73f0e981dbc8b91 Mon Sep 17 00:00:00 2001
From: Yong He <yonghe@outlook.com>
Date: Wed, 10 Jul 2024 13:27:10 -0700
Subject: Add user guide section on user-defined attributes. (#4557)

* Add user guide section on user-defined attributes.

* Update toc
---
 docs/user-guide/03-convenience-features.md | 25 +++++++++++++++++++++++++
 docs/user-guide/toc.html                   |  7 ++++---
 2 files changed, 29 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user-guide/03-convenience-features.md b/docs/user-guide/03-convenience-features.md
index a145c407c..f4cd51b3f 100644
--- a/docs/user-guide/03-convenience-features.md
+++ b/docs/user-guide/03-convenience-features.md
@@ -613,3 +613,28 @@ __file_decl
     }
 }
 ```
+
+User Defined Attributes (Experimental)
+-------------------
+
+In addition to many system defined attributes, users can define their own custom attribute types to be used in the `[UserDefinedAttribute(args...)]` syntax. The following example shows how to define a custom attribute type.
+
+```csharp
+[__AttributeUsage(_AttributeTargets.Var)]
+struct MaxValueAttribute
+{
+    int value;
+    string description;
+};
+
+[MaxValue(12, "the scale factor")]
+uniform int scaleFactor;
+```
+
+In the above code, the `MaxValueAttribute` struct type is decorated with the `[__AttributeUsage]` attribute, which informs that `MaxValueAttribute` type should be interpreted as a definiton for a user-defined attribute, `[MaxValue]`, that can be used to decorate all variables or fields. The members of the struct defines the argument list for the attribute.
+
+The `scaleFactor` uniform parameter is declared with the user defined `[MaxValue]` attribute, providing two arguments for `value` and `description`.
+
+The `_AttributeTargets` enum is used to restrict the type of decls the attribute can apply. Possible values of `_AttributeTargets` can be `Function`, `Param`, `Struct` or `Var`.
+
+The usage of user-defined attributes can be queried via Slang's reflection API through `TypeReflection` or `VariableReflection`'s `getUserAttributeCount`, `getUserAttributeByIndex` and `findUserAttributeByName` methods. 
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index d6a473faf..3443a95e8 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -46,6 +46,7 @@
 <li data-link="convenience-features#multi-level-break"><span>Multi-level break</span></li>
 <li data-link="convenience-features#force-inlining"><span>Force inlining</span></li>
 <li data-link="convenience-features#special-scoping-syntax"><span>Special Scoping Syntax</span></li>
+<li data-link="convenience-features#user-defined-attributes-experimental"><span>User Defined Attributes (Experimental)</span></li>
 </ul>
 </li>
 <li data-link="modules"><span>Modules and Access Control</span>
@@ -150,8 +151,8 @@
 </li>
 <li data-link="a1-02-slangpy"><span>Using Slang to Write PyTorch Kernels</span>
 <ul class="toc_list">
-<li data-link="a1-02-slangpy#getting-started-with-slangpy"><span>Getting Started with slangpy</span></li>
-<li data-link="a1-02-slangpy#specializing-shaders-using-slangpy"><span>Specializing shaders using slangpy</span></li>
+<li data-link="a1-02-slangpy#getting-started-with-slangtorch"><span>Getting Started with SlangTorch</span></li>
+<li data-link="a1-02-slangpy#specializing-shaders-using-slangtorch"><span>Specializing shaders using slangtorch</span></li>
 <li data-link="a1-02-slangpy#back-propagating-derivatives-through-complex-access-patterns"><span>Back-propagating Derivatives through Complex Access Patterns</span></li>
 <li data-link="a1-02-slangpy#manually-binding-kernels"><span>Manually binding kernels</span></li>
 <li data-link="a1-02-slangpy#builtin-library-support-for-pytorch-interop"><span>Builtin Library Support for PyTorch Interop</span></li>
@@ -187,4 +188,4 @@
 </li>
 </ul>
 </li>
-</ul>
+</ul>
\ No newline at end of file
-- 
cgit v1.2.3