From ab8a6120ca79a96899f3095cd44e69756f9058eb Mon Sep 17 00:00:00 2001
From: Wolfgang Bumiller <w.bumiller@proxmox.com>
Date: Mon, 23 Mar 2020 15:55:18 +0100
Subject: [PATCH] api-macro: started with some more documentation

Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>
---
 proxmox-api-macro/src/api.rs         |  9 +++++++++
 proxmox-api-macro/src/api/method.rs  |  7 +++++++
 proxmox-api-macro/src/api/structs.rs | 12 ++++++++++++
 proxmox-api-macro/src/lib.rs         |  7 +++++++
 proxmox-api-macro/src/util.rs        |  3 ++-
 5 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/proxmox-api-macro/src/api.rs b/proxmox-api-macro/src/api.rs
index bf8360ca..51a519ee 100644
--- a/proxmox-api-macro/src/api.rs
+++ b/proxmox-api-macro/src/api.rs
@@ -1,3 +1,12 @@
+//! `#[api]` macro and API schema core module.
+//!
+//! This contains the `Schema` type, which represents the schema items we have in our api library,
+//! but as seen within the `#[api]` macro context.
+//!
+//! The main job here is to parse our `util::JSONObject` into a `Schema`.
+//!
+//! The handling of methods vs type definitions happens in their corresponding submodules.
+
 use std::convert::{TryFrom, TryInto};
 
 use failure::Error;
diff --git a/proxmox-api-macro/src/api/method.rs b/proxmox-api-macro/src/api/method.rs
index 08a2b29f..3de87e30 100644
--- a/proxmox-api-macro/src/api/method.rs
+++ b/proxmox-api-macro/src/api/method.rs
@@ -1,3 +1,10 @@
+//! Method handling.
+//!
+//! This has to perform quite a few things: infer types from parameters, deal with optional types
+//! and defaults, expose parameter and return value schema to the public, and finally create the
+//! wrapper function converting from a json Value hash to the parameters listed in the function
+//! signature, while recognizing specially handling `RPCEnvironment` and `ApiMethod` parameters.
+
 use std::convert::{TryFrom, TryInto};
 use std::mem;
 
diff --git a/proxmox-api-macro/src/api/structs.rs b/proxmox-api-macro/src/api/structs.rs
index 014eed29..da7fab14 100644
--- a/proxmox-api-macro/src/api/structs.rs
+++ b/proxmox-api-macro/src/api/structs.rs
@@ -1,3 +1,15 @@
+//! `#[api]` macro for `struct` types.
+//!
+//! This module implements struct handling.
+//!
+//! We distinguish between 3 types at the moment:
+//! 1) Unit structs (`struct Foo;`),which don't do much really and aren't very useful for the API
+//!    currently)
+//! 2) Newtypes (`struct Foo(T)`), a 1-tuple, which is supposed to be a wrapper for a type `T` and
+//!    therefore should implicitly deserialize/serialize to `T`. Currently we only support simple
+//!    types for which we "know" the schema type used in the API.
+//! 3) Object structs (`struct Foo { ... }`), which declare an `ObjectSchema`.
+
 use std::collections::HashMap;
 use std::convert::{TryFrom, TryInto};
 
diff --git a/proxmox-api-macro/src/lib.rs b/proxmox-api-macro/src/lib.rs
index 74c4218e..7d1122cc 100644
--- a/proxmox-api-macro/src/lib.rs
+++ b/proxmox-api-macro/src/lib.rs
@@ -8,11 +8,17 @@ use failure::Error;
 use proc_macro::TokenStream as TokenStream_1;
 use proc_macro2::TokenStream;
 
+/// Our `format_err` macro replacement to enforce the inclusion of a `Span`.
+/// The arrow variant takes a spanned syntax element, the comma variant expects an actual `Span` as
+/// first parameter.
 macro_rules! format_err {
     ($span:expr => $($msg:tt)*) => { syn::Error::new_spanned($span, format!($($msg)*)) };
     ($span:expr, $($msg:tt)*) => { syn::Error::new($span, format!($($msg)*)) };
 }
 
+/// Our `bail` macro replacement to enforce the inclusion of a `Span`.
+/// The arrow variant takes a spanned syntax element, the comma variant expects an actual `Span` as
+/// first parameter.
 macro_rules! bail {
     ($span:expr => $($msg:tt)*) => { return Err(format_err!($span => $($msg)*).into()) };
     ($span:expr, $($msg:tt)*) => { return Err(format_err!($span, $($msg)*).into()) };
@@ -22,6 +28,7 @@ mod api;
 mod serde;
 mod util;
 
+/// Handle errors by appending a `compile_error!()` macro invocation to the original token stream.
 fn handle_error(mut item: TokenStream, data: Result<TokenStream, Error>) -> TokenStream {
     match data {
         Ok(output) => output,
diff --git a/proxmox-api-macro/src/util.rs b/proxmox-api-macro/src/util.rs
index 7cce7858..d5e3d8eb 100644
--- a/proxmox-api-macro/src/util.rs
+++ b/proxmox-api-macro/src/util.rs
@@ -526,7 +526,8 @@ pub fn is_option_type(ty: &syn::Type) -> Option<&syn::Type> {
     None
 }
 
-/// `parse_macro_input!` expects a TokenStream_1
+/// Helper to do basically what `parse_macro_input!` does, except the macro expects a
+/// `TokenStream_1`, and we always have a `TokenStream` from `proc_macro2`.
 pub struct AttrArgs {
     _paren_token: syn::token::Paren,
     pub args: Punctuated<syn::NestedMeta, Token![,]>,