From b39e2e9b26ebcdf00ccd215318680648e708db21 Mon Sep 17 00:00:00 2001
From: Max Audron <audron@cocaine.farm>
Date: Sat, 5 Jun 2021 15:09:51 +0200
Subject: document proc macros

---
 Cargo.lock                    |  7 ++++
 macros/Cargo.toml             |  9 +++++
 macros/src/lib.rs             | 81 +++++++++++++++++++++++++++++++++++++++++++
 macros/src/macro_types/mod.rs |  4 ---
 4 files changed, 97 insertions(+), 4 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index a99d564..2d27fc1 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -436,9 +436,16 @@ dependencies = [
 name = "macros"
 version = "0.1.0"
 dependencies = [
+ "anyhow",
+ "catinator",
+ "futures",
+ "irc",
  "proc-macro2",
  "quote",
+ "regex",
  "syn",
+ "tokio",
+ "tracing",
 ]
 
 [[package]]
diff --git a/macros/Cargo.toml b/macros/Cargo.toml
index 30019d7..a833e36 100644
--- a/macros/Cargo.toml
+++ b/macros/Cargo.toml
@@ -10,3 +10,12 @@ proc-macro = true
 syn = { version = "1", features = ["parsing"] }
 proc-macro2 = "1"
 quote = "1"
+
+[dev-dependencies]
+tokio = "*"
+futures = "*"
+irc = { version = "0.15", features = ["json", "tls-rust"], default_features = false }
+tracing = "*"
+anyhow = "*"
+regex = "*"
+catinator = { path = "../" }
diff --git a/macros/src/lib.rs b/macros/src/lib.rs
index 5ccf1bb..0ec317e 100644
--- a/macros/src/lib.rs
+++ b/macros/src/lib.rs
@@ -58,6 +58,69 @@ fn generate_help(items: &Items) -> proc_macro2::TokenStream {
     gen.into()
 }
 
+/// Main entrypoint to the bot
+///
+/// ```no_run
+/// # extern crate tokio;
+/// # use macros::catinator;
+/// # use anyhow::Result;
+/// #
+/// # fn function(bot: &catinator::Bot, msg: irc::client::prelude::Message) -> Result<()> {
+/// #   Ok(())
+/// # }
+/// #
+/// #[tokio::main]
+/// async fn main() {
+///   catinator!(
+///     hook("name", "A short description", PRIVMSG, function)
+///     command("name", "A short description", function)
+///     matcher("name", "A short description", r"^\[.*?\]$", function)
+///   );
+/// }
+/// ```
+///
+/// # Functions
+/// All the functions share a similar pattern,
+/// The first two arguments are the name and description respectively,
+/// the last argument is the function that gets executed.
+///
+/// The function must of of the following type:
+/// ```
+/// fn hook(bot: &catinator::Bot, msg: irc::client::prelude::Message) -> anyhow::Result<()> {
+///    Ok(())
+/// }
+/// ```
+///
+/// ## hook
+/// Hooks execute a function when a specific IRC Command is received,
+/// this allows for great flexibility in hooking into IRC for Authentication and the likes.
+///
+/// ```ignore
+/// hook("name", "description", COMMAND, function)
+/// ```
+///
+/// PRIVMSG is an IRC Command like PRIVMSG or AUTHENTICATE
+/// Any of the enum variants of [the irc crate](https://docs.rs/irc/0.15.0/irc/client/prelude/enum.Command.html)
+/// should work.
+///
+/// ## command
+/// A Command is command that can be executed in any PRIVMSG and is
+/// prefixed with the prefix configured in the config.toml file
+///
+/// ```ignore
+/// command("name", "description", function)
+/// ```
+/// Would be ":name <whatever>" in an irc channel or private message.
+///
+/// ## matcher
+/// A matcher matches on a PRIVMSG using regex.
+///
+/// ```ignore
+/// matcher("name", "description", r"regex", function)
+/// ```
+///
+/// The [regex crate](https://docs.rs/regex) is used for matching, see it's documentation for details.
+///
 #[proc_macro]
 pub fn catinator(tokens: TokenStream) -> TokenStream {
     let items = parse_macro_input!(tokens as Items);
@@ -156,6 +219,24 @@ pub fn catinator(tokens: TokenStream) -> TokenStream {
 
     return gen.into();
 }
+
+/// Match on a privmsg and execute the function block on it
+///
+/// # Examples
+/// ```
+/// # use anyhow::Result;
+/// # use irc::client::prelude::*;
+/// # use macros::privmsg;
+/// #
+/// # pub fn hook(bot: &catinator::Bot, msg: Message) -> Result<()> {
+/// privmsg!(msg, {
+///     bot.send_privmsg(
+///         msg.response_target().unwrap(),
+///         "bla",
+///     )?;
+/// })
+/// # }
+/// ```
 #[proc_macro]
 pub fn privmsg(tokens: TokenStream) -> TokenStream {
     use crate::macro_types::privmsg::Item;
diff --git a/macros/src/macro_types/mod.rs b/macros/src/macro_types/mod.rs
index 818cea7..0e55dc4 100644
--- a/macros/src/macro_types/mod.rs
+++ b/macros/src/macro_types/mod.rs
@@ -35,7 +35,6 @@ impl Parse for Items {
     }
 }
 
-#[derive(Debug)]
 pub enum Item {
     Command(Command),
     Hook(Hook),
@@ -61,7 +60,6 @@ impl Parse for Item {
     }
 }
 
-#[derive(Debug)]
 pub struct Command {
     pub name: LitStr,
     pub description: LitStr,
@@ -111,7 +109,6 @@ impl Parse for Command {
     }
 }
 
-#[derive(Debug)]
 pub struct Hook {
     pub name: LitStr,
     pub description: LitStr,
@@ -193,7 +190,6 @@ impl Parse for Hook {
     }
 }
 
-#[derive(Debug)]
 pub struct Matcher {
     pub name: LitStr,
     pub description: LitStr,
-- 
cgit v1.2.3