This is needed by the Go SIG for their adoption of weaver.

Thinking of using this: https://docs.rs/textwrap/latest/textwrap/

@jsuereth yes I had the same crate in mind.

@lquerel - Looks like it can do a bit of work, but some wonkyness - #454

Alright - the prototype is looking ok, but we'll need to sort out word splits a bit. E.g. The current algorithm in my draft PR does this:

-   // [vendor identifier]: https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor
+   // [vendor identifier]: https://developer.apple.com/documentation/uikit/
+   // uidevice/1620059-identifierforvendor

I believe I may just update the word-slicing logic to avoid seeing / as a word-break, and see how this is.

The other problematic situation - Markdown and word-wrap interactions:

-   //   - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not
+   //   - Set `error.type` to capture all errors, regardless of whether they are
+   // defined within the domain-specific set or not

@MrAlias From a go perspective, if you see markdown lists of this long variety, what would you want to see? Does go format markdown in comments?

I'm going to investigate the library a bit more to see how we could deal with this scenario.

The current algorithm in my draft PR does this:

-   // [vendor identifier]: https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor
+   // [vendor identifier]: https://developer.apple.com/documentation/uikit/
+   // uidevice/1620059-identifierforvendor

I believe I may just update the word-slicing logic to avoid seeing / as a word-break, and see how this is.

+1 to not making this split 👍

The other problematic situation - Markdown and word-wrap interactions:

-   //   - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not
+   //   - Set `error.type` to capture all errors, regardless of whether they are
+   // defined within the domain-specific set or not

@MrAlias From a go perspective, if you see markdown lists of this long variety, what would you want to see? Does go format markdown in comments?

Go does format these lists (https://tip.golang.org/doc/comment#lists). Unfortunately, it does not match exactly markdown list formatting rules. It requires a prefix space.

We do utilize this in place (https://pkg.go.dev/go.opentelemetry.io/otel/metric#hdr-Instrument_Name), but for the semconv it is sort-of used just not rendered correctly:

@MrAlias Could you verify this expected test output is my target for rendering Go?

See: https://github.com/open-telemetry/weaver/blob/e54635b8aef2058ca3df207a3e86144fca636e9a/crates/weaver_forge/expected_output/comment_format/example.go
And the config:

Looks great! 🚀

Don't celebrate too early - Think it's going to take a while to get that output :)

Going to have a think about how to use the markdown rendering + word-wrapping library together, it looks like we may be either doing our own thing or very clever point-fixes to word-splits :)