Improving DocC Default Diagnostic Formatting

Hello everyone!

I recently collaborated with ronnqvist to explore ways to enhance the default diagnostic formatting in DocC.

At present, the default diagnostic output shares the same format as the one designed for tool parsing. Consequently, it can be challenging for people to read and comprehend diagnostic output on the command line.

We believe there is significant potential to improve the readability of diagnostic output that is not intended for tool parsing. Our preliminary ideas include:

  • Displaying file paths relative to the DocC catalog instead of using absolute file paths
  • Including the relevant line of content for the diagnostic range (and possibly some surrounding context)
  • Listing related solutions, notes, and explanations alongside the main diagnostic
  • Utilizing style and colors in environments where they are supported

These ideas have led to discussions in #496 and eventually resulted in a draft pull request.

I am seeking feedback from people who are interested in these diagnostic formatting improvements. Your input will help shape the proposed changes before we mark the pull request as ready for review. Your suggestions and insights are greatly appreciated!