Add comments, improve macro error msgs

api/rust/examples/default_config/main.rs

@@ -18,59 +18,80 @@ async fn main() {
 
     let mod_key = Mod::Ctrl;
 
+    let terminal = "alacritty";
+
+    // Mousebinds
+
+    // `mod_key + left click` starts moving a window
     input.mousebind([mod_key], MouseButton::Left, MouseEdge::Press, || {
         window.begin_move(MouseButton::Left);
     });
 
+    // `mod_key + right click` starts resizing a window
     input.mousebind([mod_key], MouseButton::Right, MouseEdge::Press, || {
         window.begin_resize(MouseButton::Right);
     });
 
     // Keybinds
 
+    // `mod_key + alt + q` quits Pinnacle
     input.keybind([mod_key, Mod::Alt], 'q', || {
         pinnacle.quit();
     });
 
+    // `mod_key + alt + c` closes the focused window
     input.keybind([mod_key, Mod::Alt], 'c', || {
         if let Some(window) = window.get_focused() {
             window.close();
         }
     });
 
-    input.keybind([mod_key], Keysym::Return, || {
-        process.spawn(["alacritty"]);
+    // `mod_key + Return` spawns a terminal
+    input.keybind([mod_key], Keysym::Return, move || {
+        process.spawn([terminal]);
     });
 
+    // `mod_key + alt + space` toggles floating
     input.keybind([mod_key, Mod::Alt], Keysym::space, || {
         if let Some(window) = window.get_focused() {
             window.toggle_floating();
         }
     });
 
+    // `mod_key + f` toggles fullscreen
     input.keybind([mod_key], 'f', || {
         if let Some(window) = window.get_focused() {
             window.toggle_fullscreen();
         }
     });
 
+    // `mod_key + m` toggles maximized
     input.keybind([mod_key], 'm', || {
         if let Some(window) = window.get_focused() {
             window.toggle_maximized();
         }
     });
 
+    // Window rules
+    //
+    // You can define window rules to get windows to open with desired properties.
+    // See `pinnacle_api::window::rules` in the docs for more information.
+
     // Tags
 
     let tag_names = ["1", "2", "3", "4", "5"];
 
+    // Setup all monitors with tags "1" through "5"
     output.connect_for_all(move |op| {
         let mut tags = tag.add(&op, tag_names);
+
+        // Be sure to set a tag to active or windows won't display
         tags.next().unwrap().set_active(true);
     });
 
-    process.spawn_once(["alacritty"]);
+    process.spawn_once([terminal]);
 
+    // Create a layout cycler to cycle through the given layouts
     let LayoutCycler {
         prev: layout_prev,
         next: layout_next,
@@ -84,27 +105,32 @@ async fn main() {
         Layout::CornerBottomRight,
     ]);
 
+    // `mod_key + space` cycles to the next layout
     input.keybind([mod_key], Keysym::space, move || {
         layout_next(None);
     });
 
+    // `mod_key + shift + space` cycles to the previous layout
     input.keybind([mod_key, Mod::Shift], Keysym::space, move || {
         layout_prev(None);
     });
 
     for tag_name in tag_names {
+        // `mod_key + 1-5` switches to tag "1" to "5"
         input.keybind([mod_key], tag_name, move || {
             if let Some(tg) = tag.get(tag_name) {
                 tg.switch_to();
             }
         });
 
+        // `mod_key + shift + 1-5` toggles tag "1" to "5"
         input.keybind([mod_key, Mod::Shift], tag_name, move || {
             if let Some(tg) = tag.get(tag_name) {
                 tg.toggle_active();
             }
         });
 
+        // `mod_key + alt + 1-5` moves the focused window to tag "1" to "5"
         input.keybind([mod_key, Mod::Alt], tag_name, move || {
             if let Some(tg) = tag.get(tag_name) {
                 if let Some(win) = window.get_focused() {
@@ -113,6 +139,7 @@ async fn main() {
             }
         });
 
+        // `mod_key + shift + alt + 1-5` toggles tag "1" to "5" on the focused window
         input.keybind([mod_key, Mod::Shift, Mod::Alt], tag_name, move || {
             if let Some(tg) = tag.get(tag_name) {
                 if let Some(win) = window.get_focused() {

api/rust/pinnacle-api-macros/src/lib.rs

@@ -2,7 +2,7 @@ use proc_macro2::{Ident, Span};
 use quote::{quote, quote_spanned};
 use syn::{
     parse::Parse, parse_macro_input, punctuated::Punctuated, spanned::Spanned, Expr, Lit,
-    MetaNameValue, Token,
+    MetaNameValue, ReturnType, Stmt, Token,
 };
 
 /// Transform the annotated function into one used to configure the Pinnacle compositor.
@@ -55,7 +55,14 @@ pub fn config(
 
     if sig.asyncness.is_none() {
         return quote_spanned! {sig.fn_token.span()=>
-            compile_error!("This function must be marked `async` to run a Pinnacle config");
+            compile_error!("this function must be marked `async` to run a Pinnacle config");
+        }
+        .into();
+    }
+
+    if let ReturnType::Type(_, ty) = sig.output {
+        return quote_spanned! {ty.span()=>
+            compile_error!("this function must not have a return type");
         }
         .into();
     }
@@ -64,6 +71,12 @@ pub fn config(
 
     let stmts = item.block.stmts;
 
+    if let Some(ret @ Stmt::Expr(Expr::Return(_), _)) = stmts.last() {
+        return quote_spanned! {ret.span()=>
+            compile_error!("this function must not return, as it awaits futures after the end of this statement");
+        }.into();
+    }
+
     let module_ident = macro_input.ident;
 
     let options = macro_input.options;
@@ -106,7 +119,7 @@ pub fn config(
 
     let tokio_attr = internal_tokio.then(|| {
         quote! {
-            #[::pinnacle_api::tokio::main]
+            #[::pinnacle_api::tokio::main(crate = "::pinnacle_api::tokio")]
         }
     });
 

api/rust/src/lib.rs

@@ -170,9 +170,7 @@ pub async fn connect(
 ///
 /// This function is inserted at the end of your config through the [`config`] macro.
 /// You should use the macro instead of this function directly.
-pub async fn listen(
-    fut_recv: UnboundedReceiver<BoxFuture<'static, ()>>, // api_modules: ApiModules<'a>,
-) {
+pub async fn listen(fut_recv: UnboundedReceiver<BoxFuture<'static, ()>>) {
     let mut future_set = FuturesUnordered::<
         BoxFuture<(
             Option<BoxFuture<()>>,