Updated docs.

Author: pigpigyyy

doc/docs/de/doc/advanced/macro.md

@@ -338,3 +338,145 @@ $printNumAndStr 123, "hallo"
 </YueDisplay>
 
 Weitere Details zu verfügbaren AST-Knoten findest du in den großgeschriebenen Definitionen in `yue_parser.cpp`.
+
+## Annotation-Anweisungen
+
+Annotation-Anweisungen wenden ein Makro auf die direkt folgende Anweisung an.
+
+Das entspricht einem Makroaufruf, bei dem der Quelltext der folgenden Anweisung als letztes Argument zusätzlich übergeben wird.
+
+```yuescript
+macro ShowName = (code) -> |
+  print "#{code\match '^[%w_]*'}"
+
+$[ShowName]
+myFunc = ->
+
+return
+```
+
+<YueDisplay>
+
+```yue
+macro ShowName = (code) -> |
+  print "#{code\match '^[%w_]*'}"
+
+$[ShowName]
+myFunc = ->
+
+return
+```
+
+</YueDisplay>
+
+Wenn das Annotationsmakro eine Konfigurationstabelle zurückgibt, steuert das optionale Feld `before`, ob das Ergebnis vor oder nach der annotierten Anweisung eingefügt wird.
+
+```yuescript
+macro Tag = (tag, code) ->
+  tableName = code\match "^[%w_]+"
+  return
+    type: "text"
+    before: tag == "before"
+    code: "-- #{tag}:#{tableName}"
+
+$[Tag before]
+tableA = {}
+
+$[Tag after]
+tableB = {}
+
+return
+```
+
+<YueDisplay>
+
+```yue
+macro Tag = (tag, code) ->
+  tableName = code\match "^[%w_]+"
+  return
+    type: "text"
+    before: tag == "before"
+    code: "-- #{tag}:#{tableName}"
+
+$[Tag before]
+tableA = {}
+
+$[Tag after]
+tableB = {}
+
+return
+```
+
+</YueDisplay>
+
+Da die folgende Anweisung als zusätzliches Makroargument übergeben wird, lassen sich mit Annotationen auch direkt Registrierungszeilen aus Klassendeklarationen erzeugen. Du kannst dabei dieselben AST-Argumentprüfungen wie bei normalen Makros verwenden.
+
+```yuescript
+macro Register = (registry, code`ClassDecl) ->
+  className = code\match "^class%s+(%w+)"
+  return |
+    #{registry}["#{className}"] = #{className}
+
+registry = {}
+
+$[Register(registry)]
+class Worker
+  run: => "ok"
+
+return
+```
+
+<YueDisplay>
+
+```yue
+macro Register = (registry, code`ClassDecl) ->
+  className = code\match "^class%s+(%w+)"
+  return |
+    #{registry}["#{className}"] = #{className}
+
+registry = {}
+
+$[Register(registry)]
+class Worker
+  run: => "ok"
+
+return
+```
+
+</YueDisplay>
+
+Annotationen können auch Wrapper-Code um Funktionen herum einfügen:
+
+```yuescript
+macro ValidateNumberArgs = (code) ->
+  funcName = code\match "^(%w+)%s*="
+  return |
+    local __orig_#{funcName} = #{funcName}
+    #{funcName} = (...) ->
+      for i = 1, select "#", ...
+        assert type(select i, ...) == "number", "expected number for arg \#{i}"
+      __orig_#{funcName} ...
+
+$[ValidateNumberArgs]
+add = (a, b) -> a + b
+```
+
+<YueDisplay>
+
+```yue
+macro ValidateNumberArgs = (code) ->
+  funcName = code\match "^(%w+)%s*="
+  return |
+    local __orig_#{funcName} = #{funcName}
+    #{funcName} = (...) ->
+      for i = 1, select "#", ...
+        assert type(select i, ...) == "number", "expected number for arg \#{i}"
+      __orig_#{funcName} ...
+
+$[ValidateNumberArgs]
+add = (a, b) -> a + b
+```
+
+</YueDisplay>
+
+Auf eine Annotation muss immer eine Anweisung folgen, und sie kann nicht auf eine `return`-Anweisung angewendet werden. Wenn die annotierte Anweisung am Ende eines Blocks steht und du die rohe AST-Form der Anweisung brauchst, füge ein explizites `return` danach ein, damit sie nicht in einen implizit zurückgegebenen Ausdruck eingebettet wird.

doc/docs/doc/advanced/macro.md

@@ -68,7 +68,7 @@ if $and f1!, f2!, f3!
 
 ## Insert Raw Codes
 
-A macro function can either return a YueScript string or a config table containing Lua codes.
+A macro function can either return a YueScript string or a config table containing generated code.
 
 ```yuescript
 macro yueFunc = (var) -> "local #{var} = ->"
@@ -126,6 +126,15 @@ end
 
 </YueDisplay>
 
+The returned table can be used to control how the generated code gets inserted.
+
+- `code` is the generated text.
+- `type` chooses how the text is handled. It can be `"yue"` (the default), `"lua"`, or `"text"`.
+- `locals` declares local names introduced by inserted text.
+- `before` puts the generated result before the annotated statement instead of after it.
+
+In most cases you only need to choose a `type`. Use `"yue"` for generated YueScript, `"lua"` for raw Lua, and `"text"` for text that should be copied straight into the final output.
+
 ## Export Macro
 
 Macro functions can be exported from a module and get imported in another module. You have to put export macro functions in a single file to be used, and only macro definition, macro importing and macro expansion in place can be put into the macro exporting module.
@@ -338,3 +347,145 @@ $printNumAndStr 123, "hello"
 </YueDisplay>
 
 For more details about available AST nodes, please refer to the uppercased definitions in [yue_parser.cpp](https://github.com/IppClub/YueScript/blob/main/src/yuescript/yue_parser.cpp).
+
+## Annotation Statements
+
+Annotation statements apply a macro to the statement immediately following them.
+
+This is equivalent to calling the macro with the following statement's source text appended as the last argument.
+
+```yuescript
+macro ShowName = (code) -> |
+  print "#{code\match '^[%w_]*'}"
+
+$[ShowName]
+myFunc = ->
+
+return
+```
+
+<YueDisplay>
+
+```yue
+macro ShowName = (code) -> |
+  print "#{code\match '^[%w_]*'}"
+
+$[ShowName]
+myFunc = ->
+
+return
+```
+
+</YueDisplay>
+
+When the annotation macro returns a config table, the optional `before` field controls whether the generated result is emitted before or after the annotated statement.
+
+```yuescript
+macro Tag = (tag, code) ->
+  tableName = code\match "^[%w_]+"
+  return
+    type: "text"
+    before: tag == "before"
+    code: "-- #{tag}:#{tableName}"
+
+$[Tag before]
+tableA = {}
+
+$[Tag after]
+tableB = {}
+
+return
+```
+
+<YueDisplay>
+
+```yue
+macro Tag = (tag, code) ->
+  tableName = code\match "^[%w_]+"
+  return
+    type: "text"
+    before: tag == "before"
+    code: "-- #{tag}:#{tableName}"
+
+$[Tag before]
+tableA = {}
+
+$[Tag after]
+tableB = {}
+
+return
+```
+
+</YueDisplay>
+
+Because the followed statement is passed in as an extra macro argument, annotations can also be used to generate registration code from class declarations. Because the followed statement is passed in as an extra macro argument, you can use the same AST argument checks as normal macros:
+
+```yuescript
+macro Register = (registry, code`ClassDecl) ->
+  className = code\match "^class%s+(%w+)"
+  return |
+    #{registry}["#{className}"] = #{className}
+
+registry = {}
+
+$[Register(registry)]
+class Worker
+  run: => "ok"
+
+return
+```
+
+<YueDisplay>
+
+```yue
+macro Register = (registry, code`ClassDecl) ->
+  className = code\match "^class%s+(%w+)"
+  return |
+    #{registry}["#{className}"] = #{className}
+
+registry = {}
+
+$[Register(registry)]
+class Worker
+  run: => "ok"
+
+return
+```
+
+</YueDisplay>
+
+Annotations can also inject wrapper code around functions:
+
+```yuescript
+macro ValidateNumberArgs = (code) ->
+  funcName = code\match "^(%w+)%s*="
+  return |
+    local __orig_#{funcName} = #{funcName}
+    #{funcName} = (...) ->
+      for i = 1, select "#", ...
+        assert type(select i, ...) == "number", "expected number for arg \#{i}"
+      __orig_#{funcName} ...
+
+$[ValidateNumberArgs]
+add = (a, b) -> a + b
+```
+
+<YueDisplay>
+
+```yue
+macro ValidateNumberArgs = (code) ->
+  funcName = code\match "^(%w+)%s*="
+  return |
+    local __orig_#{funcName} = #{funcName}
+    #{funcName} = (...) ->
+      for i = 1, select "#", ...
+        assert type(select i, ...) == "number", "expected number for arg \#{i}"
+      __orig_#{funcName} ...
+
+$[ValidateNumberArgs]
+add = (a, b) -> a + b
+```
+
+</YueDisplay>
+
+An annotation must always be followed by a statement, and it can not be applied to a `return` statement. If the annotated statement appears at the end of a block, add an explicit trailing `return` when you need the raw statement AST shape instead of an implicitly returned expression.