From 30becba287872aaa9fb0e6d98a48409bc89eafc8 Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Tue, 31 Dec 2024 10:14:14 -0500
Subject: [PATCH] Minor: consolidate ConfigExtension example into API docs

---
 .../examples/config_extension.rs              | 52 -------------------
 datafusion/common/src/config.rs               | 46 +++++++++++++++-
 2 files changed, 45 insertions(+), 53 deletions(-)
 delete mode 100644 datafusion-examples/examples/config_extension.rs

diff --git a/datafusion-examples/examples/config_extension.rs b/datafusion-examples/examples/config_extension.rs
deleted file mode 100644
index b9f83f91ce56..000000000000
--- a/datafusion-examples/examples/config_extension.rs
+++ /dev/null
@@ -1,52 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements.  See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership.  The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License.  You may obtain a copy of the License at
-//
-//   http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied.  See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-//! This example demonstrates how to extend the DataFusion configs with custom extensions.
-
-use datafusion::{
-    common::{config::ConfigExtension, extensions_options},
-    config::ConfigOptions,
-};
-
-extensions_options! {
-    /// My own config options.
-    pub struct MyConfig {
-        /// Should "foo" be replaced by "bar"?
-        pub foo_to_bar: bool, default = true
-
-        /// How many "baz" should be created?
-        pub baz_count: usize, default = 1337
-    }
-}
-
-impl ConfigExtension for MyConfig {
-    const PREFIX: &'static str = "my_config";
-}
-
-fn main() {
-    // set up config struct and register extension
-    let mut config = ConfigOptions::default();
-    config.extensions.insert(MyConfig::default());
-
-    // overwrite config default
-    config.set("my_config.baz_count", "42").unwrap();
-
-    // check config state
-    let my_config = config.extensions.get::<MyConfig>().unwrap();
-    assert!(my_config.foo_to_bar,);
-    assert_eq!(my_config.baz_count, 42,);
-}
diff --git a/datafusion/common/src/config.rs b/datafusion/common/src/config.rs
index 942aa308e200..c7faeb018737 100644
--- a/datafusion/common/src/config.rs
+++ b/datafusion/common/src/config.rs
@@ -889,8 +889,50 @@ impl ConfigOptions {
     }
 }
 
-/// [`ConfigExtension`] provides a mechanism to store third-party configuration within DataFusion
+/// [`ConfigExtension`] provides a mechanism to store third-party configuration
+/// within DataFusion [`ConfigOptions`]
 ///
+/// This mechanism can be used to pass configuration to user defined functions
+/// or optimizer passes
+///
+/// # Example
+/// ```
+/// use datafusion_common::{
+///     config::ConfigExtension, extensions_options,
+///     config::ConfigOptions,
+/// };
+/// // Define a new configuration struct using the `extensions_options` macro
+/// extensions_options! {
+///     /// My own config options.
+///     pub struct MyConfig {
+///         /// Should "foo" be replaced by "bar"?
+///         pub foo_to_bar: bool, default = true
+///
+///         /// How many "baz" should be created?
+///         pub baz_count: usize, default = 1337
+///     }
+/// }
+///
+/// impl ConfigExtension for MyConfig {
+///     const PREFIX: &'static str = "my_config";
+/// }
+///
+/// fn main() {
+///     // set up config struct and register extension
+///     let mut config = ConfigOptions::default();
+///     config.extensions.insert(MyConfig::default());
+///
+///     // overwrite config default
+///     config.set("my_config.baz_count", "42").unwrap();
+///
+///     // check config state
+///     let my_config = config.extensions.get::<MyConfig>().unwrap();
+///     assert!(my_config.foo_to_bar,);
+///     assert_eq!(my_config.baz_count, 42,);
+/// }
+/// ```
+///
+/// # Note:
 /// Unfortunately associated constants are not currently object-safe, and so this
 /// extends the object-safe [`ExtensionOptions`]
 pub trait ConfigExtension: ExtensionOptions {
@@ -901,6 +943,8 @@ pub trait ConfigExtension: ExtensionOptions {
 }
 
 /// An object-safe API for storing arbitrary configuration
+/// do
+/// See [`ConfigExtension`] for user defined configuration
 pub trait ExtensionOptions: Send + Sync + fmt::Debug + 'static {
     /// Return `self` as [`Any`]
     ///