From e89a52c30bd14869da8460970da19b99e853fdb0 Mon Sep 17 00:00:00 2001
From: Dietmar Maurer <dietmar@proxmox.com>
Date: Sat, 23 Nov 2019 10:42:17 +0100
Subject: [PATCH] proxmox-api: further cleanups

- improve docs
- move  ConstRegexPattern to const_regex.rs
---
 proxmox-api/src/const_regex.rs | 33 ++++++++++++++++++++++++++++-----
 proxmox-api/src/format.rs      |  1 +
 proxmox-api/src/lib.rs         |  4 ++++
 proxmox-api/src/schema.rs      | 30 ++++++++++++------------------
 4 files changed, 45 insertions(+), 23 deletions(-)

diff --git a/proxmox-api/src/const_regex.rs b/proxmox-api/src/const_regex.rs
index 9bcedbea..a6e8ec56 100644
--- a/proxmox-api/src/const_regex.rs
+++ b/proxmox-api/src/const_regex.rs
@@ -1,10 +1,33 @@
-//! Allow to build Regex within `const_fn`
-//!
-//! The current Regex::new() function is not `const_fn`. Unless that
-//! works, we use a macro to generate something we can use inside
-//! `const_fn`.
+
+use std::fmt;
+
+/// Helper to represent const regular expressions
+///
+/// The current Regex::new() function is not `const_fn`. Unless that
+/// works, we use `ConstRegexPattern` to represent static regular
+/// expressions. Please use the `const_regex` macro to generate
+/// instances of this type (uses lazy_static).
+pub struct ConstRegexPattern {
+    /// This is only used for documentation and debugging
+    pub regex_string: &'static str,
+    /// This function return the the actual Regex
+    pub regex_obj: fn() -> &'static regex::Regex,
+}
+
+impl fmt::Debug for ConstRegexPattern {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{:?}", self.regex_string)
+    }
+}
 
 /// Macro to generate a ConstRegexPattern
+///
+/// ```ignore
+/// const_regex!{
+///    FILE_EXTENSION_REGEX = r".*\.([a-zA-Z]+)$";
+///    pub SHA256_HEX_REGEX = r"^[a-f0-9]{64}$";
+/// }
+/// ```
 #[macro_export]
 macro_rules! const_regex {
     () =>   {};
diff --git a/proxmox-api/src/format.rs b/proxmox-api/src/format.rs
index 703c86ee..16f3c17c 100644
--- a/proxmox-api/src/format.rs
+++ b/proxmox-api/src/format.rs
@@ -1,3 +1,4 @@
+//! Module to generate and format API Documenation
 use failure::*;
 
 use std::io::Write;
diff --git a/proxmox-api/src/lib.rs b/proxmox-api/src/lib.rs
index 98bc5328..8b5eb723 100644
--- a/proxmox-api/src/lib.rs
+++ b/proxmox-api/src/lib.rs
@@ -9,6 +9,7 @@ use hyper::http::request::Parts;
 use hyper::{Body, Response};
 use serde_json::Value;
 
+#[doc(hidden)]
 pub mod const_regex;
 #[doc(hidden)]
 pub mod error;
@@ -19,6 +20,9 @@ pub mod router;
 pub mod rpc_environment;
 pub mod schema;
 
+#[doc(inline)]
+pub use const_regex::ConstRegexPattern;
+
 #[doc(inline)]
 pub use rpc_environment::{RpcEnvironment, RpcEnvironmentType};
 
diff --git a/proxmox-api/src/schema.rs b/proxmox-api/src/schema.rs
index 14e60121..0d39824f 100644
--- a/proxmox-api/src/schema.rs
+++ b/proxmox-api/src/schema.rs
@@ -1,23 +1,31 @@
+//! Data types to decscribe data types.
+//!
+//! This is loosly based on JSON Schema, but uses static RUST data
+//! types. This way we can build completely static API
+//! definitions included with the programs read-only text segment.
+
 use std::fmt;
 
 use failure::*;
 use serde_json::{json, Value};
 use url::form_urlencoded;
 
-#[derive(Default, Debug, Fail)]
-pub struct ParameterError {
-    error_list: Vec<Error>,
-}
+use crate::const_regex::ConstRegexPattern;
 
 /// Error type for schema validation
 ///
 /// The validation functions may produce several error message,
 /// i.e. when validation objects, it can produce one message for each
 /// erroneous object property.
+#[derive(Default, Debug, Fail)]
+pub struct ParameterError {
+    error_list: Vec<Error>,
+}
 
 // fixme: record parameter names, to make it usefull to display errord
 // on HTML forms.
 impl ParameterError {
+
     pub fn new() -> Self {
         Self {
             error_list: Vec::new(),
@@ -142,20 +150,6 @@ impl IntegerSchema {
     }
 }
 
-/// Helper to represent const regular expressions
-///
-/// This is mostly a workaround, unless we can create const_fn Regex.
-pub struct ConstRegexPattern {
-    pub regex_string: &'static str,
-    pub regex_obj: fn() -> &'static regex::Regex,
-}
-
-impl std::fmt::Debug for ConstRegexPattern {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(f, "{:?}", self.regex_string)
-    }
-}
-
 #[derive(Debug)]
 pub struct StringSchema {
     pub description: &'static str,