[Feature Request for DOC] Provide some mechanism or system to track docs for diagnostics

[ArcturusZhang]

Clear and concise description of the problem

In our downstream emitters, we need to define quite a few diagnostic warnings or errors to enforce something that the emitter cannot handle or not recommend.
Now we could define a code and a message for it. It may not be a best practice that a message reported here would be very long to describe everything about the diagnostic, because in real life, to make sure the emitter use could be self-serving, quite a few things might need to be explained - such as, why this happens, how this happens, and the most important: what they should do to make the diagnostic gone.
I think a line of message may not be able to explain all these.
Is it possible that we could have some mechanism (maybe tspd?) to collect an extra doc we write in each individual emitter to describe everything for each diagnostic?

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[github-actions]

🎯 Issue Triage

Feature request to support extended documentation for diagnostics (warnings/errors) defined in emitters, so users can find detailed explanations (why it happens, how to fix it) beyond a short message string.

Category: Feature Request

Area: tspd

🔍 Analysis

• Currently, diagnostics defined via createDiagnosticCreator only carry a short message string.
• Downstream emitters (e.g., http-client-java, http-client-csharp, http-client-python) want to attach richer documentation per diagnostic code — covering cause, context, and remediation steps.
• The author proposes that tspd (the TypeSpec documentation tool) could be the vehicle for collecting and publishing this per-diagnostic documentation.
• This is related to the emitter framework and the tspd tooling, but the ask is primarily about tspd surfacing diagnostic-level docs contributed by individual emitters.
• No existing issue was found covering the same request.

📝 Suggested next steps

• Discuss whether tspd should support a @doc or similar annotation on diagnostic definitions to capture extended descriptions.
• Consider a convention for linking diagnostic codes to external documentation pages (e.g., via a url field in the diagnostic definition).
• Evaluate whether this is best done at the compiler/framework level (adding a documentation field to DiagnosticMessages) or purely as a tspd convention.

Generated by Agentic Triage

[timotheeguerin]

So one thing you can do today is define a url for each diagnostic code. (in createLibray when you define diagnostics). For example https://typespec.io/docs/standard-library/diags/triple-quote-indent/.

We however do not have any auto generated index or page yet.