add doc for ConfigDoc

src/common/proc_macro/src/lib.rs

@@ -265,20 +265,38 @@ pub fn session_config(input: TokenStream) -> TokenStream {
     session_config::derive_config(input).into()
 }
 
-/// This proc macro will recursively extract field comments in a struct and generate a method
-/// that can produce docs for every field.
-/// Unlike rustdoc, this tool only produces documents for fields, not including methods.
+/// This proc macro recursively extracts rustdoc comments from the fields in a struct and generates a method
+/// that produces docs for each field.
+/// Unlike rustdoc, this tool focuses solely on extracting rustdoc for struct fields, without methods.
+///
+/// Example:
 ///
 /// ```ignore
 /// #[derive(ConfigDoc)]
 /// pub struct Foo {
-///   /// This is a
+///   /// Description for `a`.
 ///   a i32,
 ///
-///   #[config_doc]
+///   #[config_doc(nested)]
 ///   b Bar,
+///
+///   #[config_doc(omitted)]
+///   dummy (),
 /// }
 /// ```
+///
+/// The `#[config_doc(nested)]` attribute indicates that the field is a nested config that will be documented in a separate section.
+/// Fields marked with `#[config_doc(omitted)]` will simply be omitted from the doc.
+///
+/// Here is the method generated by this macro:
+///
+/// ```ignore
+/// impl Foo {
+///     pub fn config_docs(name: String, docs: &mut std::collections::BTreeMap<String, Vec<(String, String)>>)
+/// }
+/// ```
+///
+/// In `test_example_up_to_date`, we further process the output of this method to generate a markdown in src/config/docs.md.
 #[proc_macro_derive(ConfigDoc, attributes(config_doc))]
 pub fn config_doc(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input);