a comment based approach would mean that tooling that operates on symbolgraphs would also need to parse and understand markdown. i can’t speak for the DocC stack, but this is a big change for Biome’s SymbolGraphs engine, which currently treats doccomment text as opaque string data.
another implication of this would be that symbolgraphs would need to embed parsed markdown trees (instead of raw markdown) since presumably we would not want to parse markdown twice, as this is already the most computationally intensive stage of documentation compilation, at least for Biome.
Biome is moving towards an AOT compilation model, and at some point, i do want to see pre-parsed markdown being stored in symbolgraph files instead of getting JITted on the server. but this would require a lot of changes to symbolgraphs in general that i don’t think we are currently prepared to undertake.
correct. my stance towards this is similar to my stance towards SE-0346 — it is not going to be practical to adopt this feature in libraries until we have some kind of lexically-scoped #if. of course, that should not delay pitching and reviewing this feature.