avr: improved apidoc

avr/modules/lcd2/gui2/generic/widget.asm

@@ -132,12 +132,10 @@ Widget_OnDraw:
   ldd r17, Y+WIDGET_SD_OFFS_FLAGS
 
   ; check whether widget is active
-  clc
   sbrs r17, WIDGET_FLAGS_ACTIVE_BIT
     rjmp Widget_OnDraw_ret
 
   ; check whether widget is dirty
-  sec
   sbrs r17, WIDGET_FLAGS_DIRTY_BIT
     rjmp Widget_OnDraw_ret
 
@@ -148,6 +146,7 @@ Widget_OnDraw:
   rcall Widget_Clear
 
 Widget_OnDraw_ret:
+  sec
   ret
 ; @end
 
@@ -378,22 +377,22 @@ Widget_UngrabTouchEvents_popRet:
 ;
 ; @param   Z       byte address of widget object (for LPM!)
 ; @param   R16     flags to add
-; @clobbers R17, R18, R19, R22, R23, Y
+; @clobbers R17, R18, R19, Y
 
 Widget_AddFlagsDown:
-  rcall OBJ_IsObject
+  rcall OBJ_IsObject                      ; (none)
   brcc Widget_AddFlagsDown_ret
 
-  rcall Widget_AddFlags                   ; (R17, R22, R23)
+  rcall Widget_AddFlags                   ; (R17)
   push zl
     push zh
-      bigcall OBJ_GetFirstChild           ; R19:R18=next object
+      bigcall OBJ_GetFirstChild           ; R19:R18=next object (none)
 Widget_AddFlagsDown_loop:
         brcc Widget_AddFlagsDown_loopEnd
         mov zl, r18
         mov zh, r19
-        rcall Widget_AddFlagsDown
-        rcall OBJ_GetNext
+        rcall Widget_AddFlagsDown         ; (R17, R18, R19, Y)
+        rcall OBJ_GetNext                 ; R19:R18=next object (none)
       rjmp Widget_AddFlagsDown_loop
       
 Widget_AddFlagsDown_loopEnd:
@@ -442,10 +441,10 @@ Widget_SubFlagsDown_ret:
 ;
 ; @param   Z       byte address of widget object (for LPM!)
 ; @param   R16     flags to add
-; @clobbers R17, R22, R23
+; @clobbers R17
 
 Widget_AddFlags:
-  rcall OBJ_IsObject
+  rcall OBJ_IsObject                          ; (none)
   brcc Widget_AddFlags_ret
 
   push yl
@@ -1156,6 +1155,21 @@ Widget_TreeMatchFlagsAndSendSignalToActive_ret:
 
 
 
+; ---------------------------------------------------------------------------
+; @routine widgetTreeMatchFlagsAndSendSignalToActive
+;
+; Send signal to all widgets whose WIDGET_SD_OFFS_FLAGS matches the given mask/value.
+; Inactive branches are skipped.
+;
+; @param  Z byte address of object (for LPM!)
+; @param  R16 signal number
+; @param  R17 selector
+; @param  R20 mask for WIDGET_SD_OFFS_FLAGS to match
+; @param  R21 value for WIDGET_SD_OFFS_FLAGS to match
+; @param  xl param1
+; @param  xh param2
+; @clobbers any, !R16, !R17, !R20, !R21, !X, !Z
+
 widgetTreeMatchFlagsAndSendSignalToActive:
   push zl
     push zh
@@ -1169,17 +1183,17 @@ widgetTreeMatchFlagsAndSendSignalToActive:
       brne widgetTreeMatchFlagsAndSendSignalToActive_l1
       push r20
         push r21
-          rcall OBJ_HandleSignalSaveInRegs
+          rcall OBJ_HandleSignalSaveInRegs                  ; (any, !R16, !R17, !X, !Z)
         pop r21
       pop r20
 widgetTreeMatchFlagsAndSendSignalToActive_l1:
-      bigcall OBJ_GetFirstChild
+      bigcall OBJ_GetFirstChild                             ; R19:R18=next (none)
 widgetTreeMatchFlagsAndSendSignalToActive_loop:
         brcc widgetTreeMatchFlagsAndSendSignalToActive_done
         mov zl, r18
         mov zh, r19
-        rcall widgetTreeMatchFlagsAndSendSignalToActive
-        bigcall OBJ_GetNext
+        rcall widgetTreeMatchFlagsAndSendSignalToActive     ; (any, !R16, !R17, !R20, !R21, !X, !Z)
+        bigcall OBJ_GetNext                                 ; R19:R18=next (none)
       rjmp widgetTreeMatchFlagsAndSendSignalToActive_loop
     
 widgetTreeMatchFlagsAndSendSignalToActive_done: