doc comments

httpd/src/act.rs

@@ -3,6 +3,7 @@ use sbcom::macros::*;
 
 use crate::{err::ActErr, CFG};
 
+/** make a formatted html string with title `format!($t)` and body `format!($b)` */
 #[macro_export]
 macro_rules! page_fmt {
     { ($($t:tt)*), ($($b:tt)*) } => {{
@@ -33,6 +34,7 @@ macro_rules! page_fmt {
     }};
 }
 
+/** return an `Ok(Html(page_fmt!(...)))` */
 macro_rules! page {
     { ($($x:tt)*), ($($y:tt)*) } => {{
         use axum::response::Html;
@@ -40,12 +42,21 @@ macro_rules! page {
     }};
 }
 
+/** log a page load */
 macro_rules! log_page {
     ($($x:tt)*) => {{
         log!("{}: {}", "viewing page".cyan(), format!($($x)*));
     }};
 }
 
+/** create a page function.
+ *
+ * generates a function with signature
+ * ```
+ * pub async fn $n($($a)*) -> Result<$t, ActErr>
+ * ```
+ * and body `$x`.
+ */
 macro_rules! mk_page {
     { $n:ident($($a:tt)*) -> $t:ty => $x:expr } => {
         pub async fn $n($($a)*) -> Result<$t, ActErr> {
@@ -55,6 +66,7 @@ macro_rules! mk_page {
     };
 }
 
+/** send a redirect with a formatted string */
 macro_rules! redirect {
     ($($x:tt)*) => {{
         use axum::response::Redirect;
@@ -62,6 +74,7 @@ macro_rules! redirect {
     }};
 }
 
+/** don't use this function; see `verify_form!`. */
 fn verify_form(v: &[(&str, &str, (usize, usize))]) -> Result<(), ActErr> {
     for (n, s, (min, max)) in v.into_iter() {
         let l = s.len();
@@ -75,6 +88,32 @@ fn verify_form(v: &[(&str, &str, (usize, usize))]) -> Result<(), ActErr> {
     Ok(())
 }
 
+/**
+ * ```
+ * verify_form!(
+ *     form struct,
+ *     $( (form field, (min length, max length)) ),*
+ * )
+ * ```
+ *
+ * for example
+ *
+ * ```
+ * struct User {
+ *     name: String,
+ *     pass: String,
+ * }
+ *
+ * mk_page! { page(Form(f): Form<User>) -> HtmlStr => {
+ *     verify_form!(
+ *         f,
+ *         (name, (1, 32)), /* name is 1-32 chars */
+ *         (pass, (8, 64)), /* pass is 8-64 chars */
+ *      )?;
+ *      ...
+ * } }
+ * ```
+ */
 macro_rules! verify_form {
     ($f:expr, $(($n:ident, ($min:expr, $max:expr))),* ) => {{
         verify_form(&[$((stringify!($n), &$f.$n, ($min, $max))),*])?;

httpd/src/err.rs

@@ -2,6 +2,9 @@ use thiserror::Error;
 use axum_thiserror::ErrorStatus;
 use http::status::StatusCode;
 
+/** action errors.
+ *
+ * see src/act.rs. */
 #[derive(Error, Debug, ErrorStatus)]
 pub enum ActErr {
     #[error("invalid form parameters: {0}")]

httpd/src/lib.rs

@@ -4,11 +4,13 @@ use lazy_static::lazy_static;
 use sbse::fatal;
 use toml::Table;
 
-use std::{cmp, fs};
+use std::fs;
 
 pub mod act;
 pub mod err;
 
+/** extract a toml field into a rust type.
+ * indexes `$x` with key `$k` and calls conversion method `$m` on the result. */
 macro_rules! toml {
     ($x:expr, $k:expr, $m:ident) => {{
         match $x[$k].$m() {
@@ -24,6 +26,7 @@ pub struct Args {
     cfg: String,
 }
 
+/** the fields in the cfg.toml file */
 pub struct Cfg {
     pub addr: String,
     pub port: i64,
@@ -31,8 +34,11 @@ pub struct Cfg {
     pub version: String,
 }
 
+/* TODO: OnceCell */
 lazy_static! {
+    /** the cli arguments */
     pub static ref ARGS: Args = Args::parse();
+    /** the global config */
     pub static ref CFG: Cfg = {
         let t = match fs::read_to_string(&ARGS.cfg) {
             Ok(x) => x,
@@ -51,14 +57,6 @@ lazy_static! {
     };
 }
 
-pub fn truncate<T>(x: T, n: usize) -> String
-where
-    String: From<T>,
-{
-    let x = String::from(x);
-    format!("{}", &x[0..cmp::min(n, x.len())])
-}
-
 pub fn fmt_date<T>(x: DateTime<T>) -> String
 where
     T: TimeZone,
@@ -67,14 +65,6 @@ where
     x.format("%Y-%m-%d %H:%M:%S").to_string()
 }
 
-pub fn fmt_unix(x: i64) -> String {
-    fmt_date(match DateTime::from_timestamp(x, 0) {
-        Some(x) => x,
-        /* uh oh ! */
-        None => fatal!("failed to format unix timestamp {x}"),
-    })
-}
-
 pub fn now_timestamp() -> i64 {
     chrono::Local::now().timestamp()
 }