chore: enhance config docs

[Jiloc]

Description

This PR contains only formatting changes to the doc comments. The goal is to simplify the format to make it easier to programmatically extract and parse.

• Introduces @default, @notes, and @toml_example blocks

Applicable issues

• sixth step of Document config.toml options automatically #5898

Checklist

• Test coverage for new or modified code paths
• Changelog is updated
• Required documentation changes (e.g., docs/rpc/openapi.yaml and rpc-endpoints.md for v2 endpoints, event-dispatcher.md for new events)
• New clarity functions have corresponding PR in clarity-benchmarking repo
• New integration test(s) added to bitcoin-tests.yml

[wileyj]

@Jiloc really good start - i don't envy what you did here, just reading through it was no small task due to the nature of these changes, and as much as i would like to say "let's break this up into several PR's" - that would not be ideal here.

overall, i like the proposed changes - there are a few nits and i think we should define the syntax a little better, possibly adding some more fields to the proposed syntax vs keeping them as normal comment lines. it almost looks like yamldown but not quite - so the rules in the changes can be a bit confusing at first glance. almost like they're oversimplified for brevity, but that leads to a lot of text that won't fit into this syntax (not necessarily a bad thing, but i think this PR needs to be explicit on what the syntax is, and how it should be applied consistently).

i would also like to hear about how these changes will help with parsing/extracting/rendering these comments to some output that can be consumed. for example, if there is a process or tool in mind, that could help inform what the syntax should look like globally.

edit: several of my comments above can be applied throughout the diff, but to reduce noise and repeating myself i've only marked a few examples where i think a change would be appropriate, with the expectation that later instances would use the same changes/rules.

[wileyj]

#6171

[wileyj]

https://github.com/Jiloc/stacks-core/blob/feat/config-docs-generator/docs/generated/configuration-reference.md

thanks! i think the syntax definition is fine to leave in #6171

in light of that, i'll check and resolve some existing comments here that may now be answered with that def.

[hstove]

Awesome!

[fdefelici]

lgmt!

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.60%. Comparing base (2493ed1) to head (3790bb8).
Report is 10 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #6168      +/-   ##
===========================================
+ Coverage    77.27%   83.60%   +6.32%     
===========================================
  Files          545      545              
  Lines       392359   392359              
  Branches       323      323              
===========================================
+ Hits        303184   328017   +24833     
+ Misses       89167    64334   -24833     
  Partials         8        8              

Files with missing lines	Coverage Δ
stackslib/src/config/mod.rs	73.39% <ø> (+1.36%)	⬆️

... and 203 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2493ed1...3790bb8. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.