cfggen: recognize comments in the struct while generating output

[Dentrax]

Is your proposal related to a problem?

As we discussed with @saswatamcode at PR #4749, the problem simply identifies that we had better to improve the tracing configuration doc as we proposed at #4748.

(Write your answer here.)

Describe the solution you'd like

We have to do some enhancements in the scripts/cfggen to make that tool recognize the comments.

Let's assume we have the following config struct:

// Config - YAML configuration.
type Config struct {
  // Foo used for to store string
  Foo  string   `yaml:"foo"`
  // Bar used for to store bool
  // true by default
  Bar  bool     `yaml:"bar"`
  // Baz used for to store float64
  Baz  float64  `yaml:"baz"`
}

cfggen should generate the following yaml snippet:

type: JAEGER
config:
  # Foo used for to store string
  foo: ""
  # Bar used for to store bool
  # true by default
  bar: false
  # Baz used for to store float64
  baz: 0

Describe alternatives you've considered

We can add Markdown table in below for each configuration like the following:

Property	Description
sampler_type	The sampler type: remote , const , probabilistic , ratelimiting (default remote). More information

[matej-g]

I'm wondering if this is meaningful, given that here we copy verbatim from the documentation that we link to. For me personally this adds more noise, when users can find the same information under the linked details. Opinions?

[saswatamcode]

Yes, in this particular case it doesn't make much sense to have as there are detailed docs regarding tracing config which we can link to.

But in the case of some Thanos-specific config (eg QueryAPI) or config without descriptive docs to link to, it can be nice to have. cfggen can then directly pull comments from source code and generate YAML (which is pasted into code blocks by mdox) and docs get updated automatically if there is some config change with relevant details. 🙂

Currently, mdox uses cfggen script using mdox-exec to generate YAML code blocks, but there's also an idea to downstream cfggen to mdox and generate YAML directly from Go struct, in which case cfggen support for comments and default values, might be beneficial to projects that use it!

[matej-g]

I see now, I missed the full context (that we want this for all configs). Sounds good! Maybe then you could consider having option to generate with or without comments included for cases like this?

[saswatamcode]

Yes, plan to have certain flags/options to support this! :)

[stale]

Hello 👋 Looks like there was no activity on this issue for the last two months.
Do you mind updating us on the status? Is this still reproducible or needed? If yes, just comment on this PR or push a commit. Thanks! 🤗
If there will be no activity in the next two weeks, this issue will be closed (we can always reopen an issue if we need!). Alternatively, use remind command if you wish to be reminded at some point in future.

[stale]

Closing for now as promised, let us know if you need this to be reopened! 🤗