Minor: consolidate ConfigExtension example into API docs (apache#13954)

* Update examples README.md

* Minor: consolidate ConfigExtension example into API docs

* more docs

* Remove update

* clippy

* Fix issue with ExtensionsOptions docs

datafusion/common/src/config.rs

@@ -895,8 +895,48 @@ 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";
+///  }
+///
+///  // 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 {
@@ -906,7 +946,9 @@ pub trait ConfigExtension: ExtensionOptions {
     const PREFIX: &'static str;
 }
 
-/// An object-safe API for storing arbitrary configuration
+/// An object-safe API for storing arbitrary configuration.
+///
+/// See [`ConfigExtension`] for user defined configuration
 pub trait ExtensionOptions: Send + Sync + fmt::Debug + 'static {
     /// Return `self` as [`Any`]
     ///
@@ -1114,6 +1156,8 @@ pub trait Visit {
 /// - `<default_value>`: Default value matching the field type like `42`.
 ///
 /// # Example
+/// See also a full example on the [`ConfigExtension`] documentation
+///
 /// ```
 /// use datafusion_common::extensions_options;
 ///