Add a way to add comments and TOML sections to config files

[sburris0]

Comments can make config files more user-friendly by giving hints about possible values and where more info can be found.
When config files get large, sections are useful to break it up so that things are easier to find.

Thanks for making this, confy made my life much much easier today.

[matthiasbeyer]

So, as far as I see, this crate uses the default toml implementation for rust: The toml crate. The toml crate is toml compliant, thus you can simply use comments in your config files:

# this is a comment
foo = "bar"

Right? Or am I missing something?

[Zykino]

I am not an expert of the toml crate. But like @matthiasbeyer said, you can add comments manually, however I think that you cannot write a configuration with comments. I have never seen a way to manage comments in a config file programmatically.

[sburris0]

So, as far as I see, this crate uses the default toml implementation for rust: The toml crate. The toml crate is toml compliant, thus you can simply use comments in your config files:

# this is a comment
foo = "bar"

Right? Or am I missing something?

I should have been more specific.
I want comments to be generated when the config file is created as most configuration files come pre-commented for clarity:

# make sxhkd reload its configuration files:
super + Escape
    pkill -USR1 -x sxhkd

#
# bspwm hotkeys
#

# quit/restart bspwm
super + alt + {q,r}
    bspc {quit,wm -r}

Cargo.toml has a note: # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[matthiasbeyer]

On 15-02-2021 10:42:49, Spencer Burris wrote: `Cargo.toml` has a note: `# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html`

I'd say that's because `Cargo.toml` is not generated from a struct, but simply copied from a template.

[ethever]

gpt 4.5 call me write a macro to do this:

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(ConfigComments)]
pub fn config_comments(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);

    let struct_ident = &input.ident;

    let mut comments = vec![];

    if let syn::Data::Struct(data_struct) = &input.data {
        for field in &data_struct.fields {
            let field_ident = field.ident.as_ref().unwrap().to_string();
            let mut doc_comment = String::new();

            for attr in &field.attrs {
                if attr.path().is_ident("doc") {
                    let doc: syn::LitStr = attr.parse_args().unwrap();
                    let doc_line = doc.value().trim();
                    if !doc_comment.is_empty() {
                        doc_comment.push(' ');
                    }
                    doc_comment.push_str(doc_line);
                }
            }

            if !doc_comment.is_empty() {
                comments.push((field_ident, doc_comment));
            }
        }
    }

    let comment_entries = comments.iter().map(|(field, comment)| {
        quote! {
            doc[#field].decor_mut().set_prefix(concat!("\n# ", #comment, "\n"));
        }
    });

    let expanded = quote! {
        impl #struct_ident {
            pub fn add_toml_comments(doc: &mut toml_edit::Document) {
                #(#comment_entries)*
            }
        }
    };

    TokenStream::from(expanded)
}

here is how i would use it:

use serde::{Serialize, Deserialize};
use config2toml::ConfigComments;
use toml_edit::Document;

#[derive(Serialize, Deserialize, Debug, ConfigComments)]
pub struct AppConfigurationV2 {
    /// Configuration for on-chain price fetching
    pub onchain_price_fetcher_config: OnchainPriceFetcherConfig,
    /// Configuration for the RPC provider
    pub provider_config: ProviderConfig,
    /// Configuration for the strategy execution
    pub strategy_config: StrategyConfig,
    /// Configuration for Gate.io integration (optional)
    pub gateio_config: Option<GateioConfig>,
    /// Configuration for gas price fetching
    pub gas_price_fetcher_config: GasPriceFetcherConfig,
    /// Logger configuration
    pub logger_config: LoggerConfig,
}

#[derive(Serialize, Deserialize, Debug, ConfigComments)]
pub struct OnchainPriceFetcherConfig {
    /// QuoterV2 contract address
    pub quoter_v2_address: String,
    /// CLPool contract address
    pub clpool_address: String,
    /// Helper contract address
    pub helper_contract_address: String,
    /// Use Token0 as the quote token
    pub token0_as_quote_token: bool,
    /// Calculate intrinsic value in Token0
    pub intrinsic_value_in_token0: bool,
}

// Other structs similarly...

This is what you want?