From fb93a40240c0bc504d14c58eac9a0fb75b44e386 Mon Sep 17 00:00:00 2001
From: Bugen Zhao <i@bugenzhao.com>
Date: Mon, 18 Sep 2023 20:21:36 +0800
Subject: [PATCH] better doc

---
 sqllogictest/src/parser.rs       | 1 +
 sqllogictest/src/runner.rs       | 5 +++--
 sqllogictest/src/substitution.rs | 3 +++
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/sqllogictest/src/parser.rs b/sqllogictest/src/parser.rs
index 39d79b1..0e59ddd 100644
--- a/sqllogictest/src/parser.rs
+++ b/sqllogictest/src/parser.rs
@@ -294,6 +294,7 @@ impl<T: ColumnType> std::fmt::Display for Record<T> {
     }
 }
 
+/// Whether to enable or disable a feature. Used in `control` statements.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum OnOff {
     On,
diff --git a/sqllogictest/src/runner.rs b/sqllogictest/src/runner.rs
index f6d5abe..2799151 100644
--- a/sqllogictest/src/runner.rs
+++ b/sqllogictest/src/runner.rs
@@ -21,6 +21,7 @@ use crate::parser::*;
 use crate::substitution::Substitution;
 use crate::{ColumnType, Connections, MakeConnection};
 
+/// Type-erased error type.
 type AnyError = Arc<dyn std::error::Error + Send + Sync>;
 
 #[derive(Debug, Clone)]
@@ -1067,8 +1068,8 @@ impl<D: AsyncDB, M: MakeConnection<Conn = D>> Runner<D, M> {
         block_on(self.run_parallel_async(glob, hosts, conn_builder, jobs))
     }
 
-    /// Substitute the input SQL or command with environment variables and `__TEST_DIR__`, if
-    /// enabled with `control`.
+    /// Substitute the input SQL or command with [`Substitution`], if enabled by `control
+    /// substitution`.
     fn may_substitute(&self, input: String) -> Result<String, AnyError> {
         if let Some(substitution) = &self.substitution {
             subst::substitute(&input, substitution).map_err(|e| Arc::new(e) as AnyError)
diff --git a/sqllogictest/src/substitution.rs b/sqllogictest/src/substitution.rs
index f376c0c..7ca27da 100644
--- a/sqllogictest/src/substitution.rs
+++ b/sqllogictest/src/substitution.rs
@@ -3,8 +3,11 @@ use std::sync::OnceLock;
 use subst::Env;
 use tempfile::{tempdir, TempDir};
 
+/// Substitute environment variables and special variables like `__TEST_DIR__` in SQL.
 #[derive(Default)]
 pub(crate) struct Substitution {
+    /// The temporary directory for `__TEST_DIR__`.
+    /// Lazily initialized and cleaned up when dropped.
     test_dir: OnceLock<TempDir>,
 }