Describe behavior of switch and goto_block

lucic71 · lucic71 · commit d40aeead536c · 2026-04-23T15:00:11.000+01:00
diff --git a/libcc2rs-macros/src/lib.rs b/libcc2rs-macros/src/lib.rs
@@ -7,23 +7,65 @@ mod goto;
 mod state_machine;
 mod switch;
 
-// switch!(match <condition> {
-//     <pat> [if <guard>] => <body>,
-//     <pat> [if <guard>] => <body>,
-//     ...
-//     _ => <body>,
-// });
+//     switch!(match <condition> {
+//         <pat> [if <guard>] => { /* body; may contain break or continue */ },
+//         ...
+//         _ => <body>,
+//     });
+//
+// Desugars to a goto_block! with a synthetic dispatch arm prepended.
+//
+//     goto_block! {
+//         '__dispatch => {
+//             match <condition> {
+//                 <pat_1> => { __s = 1; continue '__sm; }
+//                 ...
+//                 _       => break '__sm,
+//             }
+//         },
+//         '__c1 => { /* body_1 with `break` rewritten to `break '__sm` */ },
+//         ...
+//         '__cN => { /* body_N with same rewrite */ },
+//     };
+//
+// __sm is the inner label used to describe the state machine insinde goto_block. See goto_block!
+// for more info.
 
 #[proc_macro]
 pub fn switch(input: TokenStream) -> TokenStream {
     switch::expand(input)
 }
 
-// goto_block! {
-//     '<label> => <body>,
-//     '<label> => <body>,
-//     ...
-// };
+//     goto_block! {
+//         '<label> => { /* body; may contain `break` or `continue` */ },
+//         ...
+//     };
+//
+// Expands to
+//
+//     {
+//         let mut __user_break:    bool = false; // only if any arm has `break`
+//         let mut __user_continue: bool = false; // only if any arm has `continue`
+//         let mut __s: u32 = 0;
+//         '__sm: loop {
+//             match __s {
+//                 0u32 => {
+//                     /* body_0 with these rewrites (outside nested user loops): */
+//                     /*   break;    ->  { __user_break    = true; break '__sm; } */
+//                     /*   continue; ->  { __user_continue = true; break '__sm; } */
+//                     __s = 1; continue '__sm;
+//                 }
+//                 ...
+//                 (N-1)u32 => { /* body_N-1 with same rewrites */ break '__sm; }
+//                 _        => break '__sm, // written only for match exhaustiveness
+//             }
+//         }
+//         if __user_break    { break; }    // only if any arm has `break;`
+//         if __user_continue { continue; } // only if any arm has `continue;`
+//     }
+//
+//  __user_break and __user_continue propagate the `break`s and `continue`s outside the goto state
+//  machine loop.
 
 #[proc_macro]
 pub fn goto_block(input: TokenStream) -> TokenStream {
