feat: experimental doc comment formatting

[QuadnucYard]

Summary

Doc comments (/// comment), although not admitted by the official, are already widely used in existing projects.
This PR introduces basic support for doc comment formatting.

We create a sub-formatter for doc comments, which inherits the config of its parent.

• If wrap_doc_comments is set to true, the inner config also sets wrap_text to true.
• The inner max_width uses parental doc_comment_width.

Since we do not have a prefix element in the format engine, currently we have to print the contents of doc comments into strings, and then place them back to the document.

Changes

Checklist

Before submitting, please ensure you've done the following:

• Updated CHANGELOG.md: Added your changes with examples to the changelog
• Updated documentation: Updated relevant docs, examples, or README
• Added tests: Added tests for new features or bug fixes

Testing

Additional Notes

[github-actions]

📊 Benchmark Performance Report

group                               base                                   pr
-----                               ----                                   --
pretty-ai-comprehensive-showcase    1.00    900.5±9.77µs        ? ?/sec    1.02    916.9±9.70µs        ? ?/sec
pretty-cetz-manual                  1.01   758.7±28.30µs        ? ?/sec    1.00   754.9±11.32µs        ? ?/sec
pretty-codly                        1.00  1789.9±21.58µs        ? ?/sec    1.02  1819.1±25.32µs        ? ?/sec
pretty-cpe                          1.59     19.2±3.91ms        ? ?/sec    1.00     12.1±0.11ms        ? ?/sec
pretty-deep-nested-args             1.02     18.3±0.12µs        ? ?/sec    1.00     18.0±0.22µs        ? ?/sec
pretty-fletcher-diagram             1.00    520.7±9.77µs        ? ?/sec    1.02    533.2±9.94µs        ? ?/sec
pretty-fletcher-draw                1.00  1258.1±10.88µs        ? ?/sec    1.02  1287.8±11.30µs        ? ?/sec
pretty-tablex                       1.00      3.4±0.02ms        ? ?/sec    1.02      3.5±0.02ms        ? ?/sec
pretty-touying-core                 1.00      2.2±0.02ms        ? ?/sec    1.01      2.2±0.01ms        ? ?/sec
pretty-touying-utils                1.00  1209.1±17.18µs        ? ?/sec    1.02  1232.1±23.36µs        ? ?/sec
pretty-undergraduate-math           1.00   868.6±17.34µs        ? ?/sec    1.00   868.0±12.09µs        ? ?/sec

📏 Binary Size Comparison

Metric	Base	PR	Change
File Size	5.7 MB	5.8 MB	📈 +19.3 kB (+0.33%)
Text Section	1.4 MB	1.4 MB	📈 +13.5 kB (+0.96%)

📦 Detailed Crate Size Diff (cargo-bloat)

Note: Numbers above are a result of guesswork. They are not 100% correct and never will be.

@@ -1,20 +1,20 @@
-std                       397.8 kB
-clap_builder              338.9 kB
-typstyle_core             203.0 kB
-typst_syntax              140.9 kB
+std                       397.2 kB
+clap_builder              340.3 kB
+typstyle_core             208.7 kB
+typst_syntax              141.1 kB
 clap_complete             131.2 kB
-typstyle                  55.3 kB
-similar                   34.3 kB
+typstyle                  60.8 kB
+similar                   33.3 kB
 walkdir                   19.7 kB
-toml_edit                 9.1 kB
+toml_edit                 9.9 kB
 colored                   9.0 kB
-anyhow                    8.5 kB
-prettyless                7.3 kB
+prettyless                8.9 kB
+anyhow                    8.6 kB
 clap_lex                  4.2 kB
 path_absolutize           4.2 kB
 hashbrown                 4.1 kB
 parking_lot               2.6 kB
-anstream                  2.5 kB
+anstream                  2.6 kB
 ecow                      2.4 kB
 anstyle                   2.4 kB
 parking_lot_core          2.2 kB

Generated by GitHub Actions on 2025-08-07 12:29:24 UTC

[QuadnucYard]

found a problem with text-wrapping:
the break-suppressing rule should be also applied

[Enter-tainer]

I would prefer not merging this at least for now. It would be ok to kept a branch for this feature.

Considerations:

1. We are going too far. Doc comments are not recognized by official team yet. And there is no user-in-wild requesting this feature. There is not agreement on the syntax and notation of doc comments either. At this moment, I think we should not pay too much attention on it as it may change a lot in future. We should avoid accumulate technical debt for these unclear things.
2. Too many new config items. This adds complexity for develops and end users. I really like the idea that your product should be extremely simple and usable from Simple and Usable--Web,Mobile and Interaction Design. I would recommend you read this little book if you have time.