Include documentation in printed config files (#41)

* Start work on printing toml config with comments

* WIP: toml_config: extract default values for fields

* WIP: toml_config: handle single-level nested structs

* WIP: toml_config: improve comment handling, std type trait impls

* WIP: toml_config: add Private trait, improve comment handling, clean up

* toml_config: fix default value bug; improve tests

* Use toml_config in all applicable crates; add toml_config enum support

* toml_config: improve comments

* toml_config_derive: support enum comments

* Improve config comments for udp, cli_helpers, common

* Improve config comments

* Add tests for Config struct TomlConfig implementations

* Improve Config comments

* Improve Config comments

* ws, http: add config comments for tls cert and private key lines

* small fixes to toml_config and toml_config_derive

* Run cargo fmt

* Fix typo in several config comments

* Update README

* Update README

toml_config/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "toml_config"
+version = "0.1.0"
+authors = ["Joakim Frostegård <joakim.frostegard@gmail.com>"]
+edition = "2021"
+license = "Apache-2.0"
+description = "WebTorrent tracker protocol"
+repository = "https://github.com/greatest-ape/aquatic"
+exclude = ["target"]
+
+[lib]
+name = "toml_config"
+
+[dependencies]
+toml = "0.5"
+toml_config_derive = { path = "../toml_config_derive" }
+
+[dev-dependencies]
+serde = { version = "1.0", features = ["derive"] }
+quickcheck = "1"
+quickcheck_macros = "1"

toml_config/src/lib.rs

@@ -0,0 +1,126 @@
+pub use toml;
+pub use toml_config_derive::TomlConfig;
+
+/// Run this on your struct implementing TomlConfig to generate a
+/// serialization/deserialization test for it.
+#[macro_export]
+macro_rules! gen_serialize_deserialize_test {
+    ($ident:ident) => {
+        #[test]
+        fn test_cargo_toml_serialize_deserialize() {
+            use ::toml_config::TomlConfig;
+            let serialized = $ident::default_to_string();
+            let deserialized = ::toml_config::toml::de::from_str(&serialized).unwrap();
+
+            assert_eq!($ident::default(), deserialized);
+        }
+    };
+}
+
+/// Export structs to toml, converting Rust doc strings to comments.
+///
+/// Supports one level of nesting. Fields containing structs must come
+/// after regular fields.
+///
+/// Usage:
+/// ```
+/// use toml_config::TomlConfig;
+///
+/// #[derive(TomlConfig)]
+/// struct SubConfig {
+///     /// A
+///     a: usize,
+///     /// B
+///     b: String,
+/// }
+///
+/// impl Default for SubConfig {
+///     fn default() -> Self {
+///         Self {
+///             a: 200,
+///             b: "subconfig hello".into(),
+///         }
+///     }
+/// }
+///
+/// #[derive(TomlConfig)]
+/// struct Config {
+///     /// A
+///     a: usize,
+///     /// B
+///     b: String,
+///     /// C
+///     c: SubConfig,
+/// }
+///
+/// impl Default for Config {
+///     fn default() -> Self {
+///         Self {
+///             a: 100,
+///             b: "hello".into(),
+///             c: Default::default(),
+///         }
+///     }
+/// }
+///
+/// let expected = "# A\na = 100\n# B\nb = \"hello\"\n\n# C\n[c]\n# A\na = 200\n# B\nb = \"subconfig hello\"\n";
+///
+/// assert_eq!(
+///     Config::default_to_string(),
+///     expected,
+/// );
+/// ```
+pub trait TomlConfig: Default {
+    fn default_to_string() -> String;
+}
+
+pub mod __private {
+    use std::net::SocketAddr;
+    use std::path::PathBuf;
+
+    pub trait Private {
+        fn __to_string(&self, comment: Option<String>, field_name: String) -> String;
+    }
+
+    macro_rules! impl_trait {
+        ($ident:ident) => {
+            impl Private for $ident {
+                fn __to_string(&self, comment: Option<String>, field_name: String) -> String {
+                    let mut output = String::new();
+
+                    if let Some(comment) = comment {
+                        output.push_str(&comment);
+                    }
+
+                    let value = crate::toml::ser::to_string(self).unwrap();
+
+                    output.push_str(&format!("{} = {}\n", field_name, value));
+
+                    output
+                }
+            }
+        };
+    }
+
+    impl_trait!(isize);
+    impl_trait!(i8);
+    impl_trait!(i16);
+    impl_trait!(i32);
+    impl_trait!(i64);
+
+    impl_trait!(usize);
+    impl_trait!(u8);
+    impl_trait!(u16);
+    impl_trait!(u32);
+    impl_trait!(u64);
+
+    impl_trait!(f32);
+    impl_trait!(f64);
+
+    impl_trait!(bool);
+
+    impl_trait!(String);
+
+    impl_trait!(PathBuf);
+    impl_trait!(SocketAddr);
+}

toml_config/tests/test.rs

@@ -0,0 +1,46 @@
+use serde::Deserialize;
+
+use toml_config::{gen_serialize_deserialize_test, TomlConfig};
+
+#[derive(Clone, Debug, PartialEq, Eq, TomlConfig, Deserialize)]
+struct TestConfigInnerA {
+    /// Comment for a
+    a: String,
+    /// Comment for b
+    b: usize,
+}
+
+impl Default for TestConfigInnerA {
+    fn default() -> Self {
+        Self {
+            a: "Inner hello world".into(),
+            b: 100,
+        }
+    }
+}
+
+/// Comment for TestConfig
+#[derive(Clone, Debug, PartialEq, Eq, TomlConfig, Deserialize)]
+struct TestConfig {
+    /// Comment for a that stretches over
+    /// multiple lines
+    a: String,
+    /// Comment for b
+    b: usize,
+    c: bool,
+    /// Comment for TestConfigInnerA
+    inner_a: TestConfigInnerA,
+}
+
+impl Default for TestConfig {
+    fn default() -> Self {
+        Self {
+            a: "Hello, world!".into(),
+            b: 100,
+            c: true,
+            inner_a: Default::default(),
+        }
+    }
+}
+
+gen_serialize_deserialize_test!(TestConfig);