From bfab0e8798d76380d0f1b754b790ca1ec235679f Mon Sep 17 00:00:00 2001
From: Lukas Kalbertodt <lukas.kalbertodt@gmail.com>
Date: Thu, 29 Apr 2021 19:00:36 +0200
Subject: [PATCH] Add example module for documentation

It currently doesn't show anything as all items are pub(crate).
---
 Cargo.toml         | 10 +++++++++-
 examples/simple.rs |  4 ++--
 macro/src/gen.rs   |  8 ++++----
 src/example.rs     | 35 +++++++++++++++++++++++++++++++++++
 src/lib.rs         |  4 +++-
 5 files changed, 53 insertions(+), 8 deletions(-)
 create mode 100644 src/example.rs

diff --git a/Cargo.toml b/Cargo.toml
index b80b805..d577996 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,9 +4,17 @@ version = "0.1.0"
 authors = ["Lukas Kalbertodt <lukas.kalbertodt@gmail.com>"]
 edition = "2018"
 
+
 [dependencies]
 confique-macro = { path = "macro" }
 serde = { version = "1", features = ["derive"] }
+log = { version = "0.4", features = ["serde"], optional = true }
 
 [dev-dependencies]
-log = { version = "0.4", features = ["serde", "std"] }
+log = { version = "0.4", features = ["serde"] }
+
+
+[features]
+# This is used to enable the `example` module. This is only useful to generate
+# the docs for this library!
+doc-example = ["log"]
diff --git a/examples/simple.rs b/examples/simple.rs
index 8b11f20..c0b731d 100644
--- a/examples/simple.rs
+++ b/examples/simple.rs
@@ -10,10 +10,10 @@ mod config {
             level: log::LevelFilter = "debug",
 
             /// If this is set, log messages are also written to this file.
-            #[example = "/var/log/tobira.log"]
+            #[example = "/var/log/test.log"]
             file: Option<PathBuf>,
         }
-    }
+    },
 }
 
 
diff --git a/macro/src/gen.rs b/macro/src/gen.rs
index 8020546..e15bbcc 100644
--- a/macro/src/gen.rs
+++ b/macro/src/gen.rs
@@ -56,7 +56,7 @@ fn gen_raw_mod(input: &Input, visibility: &TokenStream) -> TokenStream {
 
                         quote! {
                             #name: Some({
-                                let result: Result<_, ::confique::serde::de::value::Error>
+                                let result: Result<_, confique::serde::de::value::Error>
                                     = Deserialize::deserialize(#expr.into_deserializer());
                                 result.expect(#msg)
                             }),
@@ -83,7 +83,7 @@ fn gen_raw_mod(input: &Input, visibility: &TokenStream) -> TokenStream {
             });
 
             contents.extend(quote! {
-                #[derive(Debug, Default, ::confique::serde::Deserialize)]
+                #[derive(Debug, Default, confique::serde::Deserialize)]
                 #[serde(deny_unknown_fields)]
                 #visibility struct #type_name {
                     #raw_fields
@@ -116,7 +116,7 @@ fn gen_raw_mod(input: &Input, visibility: &TokenStream) -> TokenStream {
         /// These types implement `serde::Deserialize`.
         mod raw {
             use super::*;
-            use ::confique::serde::{Deserialize, de::IntoDeserializer};
+            use confique::serde::{Deserialize, de::IntoDeserializer};
 
             #contents
         }
@@ -176,7 +176,7 @@ fn gen_root_mod(input: &Input, visibility: &TokenStream) -> TokenStream {
                 }
 
                 impl std::convert::TryFrom<raw::#type_name> for #type_name {
-                    type Error = ::confique::TryFromError;
+                    type Error = confique::TryFromError;
                     fn try_from(src: raw::#type_name) -> Result<Self, Self::Error> {
                         Ok(Self {
                             #try_from_fields
diff --git a/src/example.rs b/src/example.rs
new file mode 100644
index 0000000..6bf1b9a
--- /dev/null
+++ b/src/example.rs
@@ -0,0 +1,35 @@
+//! This module demonstrate what a `config!` invocation will generate. This
+//! module exists merely for documentation purposes and is not usable from your
+//! crate.
+//!
+//! TODO
+
+use std::{net::IpAddr, path::PathBuf};
+
+// This is necessary because the macro generates a bunch of paths starting with
+// `confique`, assuming that symbol is in scope.
+#[doc(hidden)]
+use crate as confique;
+
+crate::config! {
+    dns: {
+        /// The DNS server IP address.
+        #[example = "1.1.1.1"]
+        server: IpAddr,
+
+        /// Whether to use a local DNS resolution cache.
+        use_cache: bool = true,
+
+        /// How often to reattempt reaching the DNS server.
+        retry_attempts: u32 = 27,
+    },
+    log: {
+        /// Sets the log level. Possible values: "trace", "debug", "info",
+        /// "warn", "error" and "off".
+        level: log::LevelFilter = "info",
+
+        /// If this is set, log messages are also written to this file.
+        #[example = "/var/log/test.log"]
+        file: Option<PathBuf>,
+    },
+}
diff --git a/src/lib.rs b/src/lib.rs
index 02cf49c..76952cc 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,10 +1,12 @@
+use std::fmt;
 
 pub use confique_macro::config as config;
 
 pub use serde;
 
 
-use std::fmt;
+#[cfg(feature = "doc-example")]
+pub mod example;
 
 
 /// Error for the `TryFrom` conversion from raw types to the main types.