Design-of-Error-Messages.md

+# Communication from the Compiler
+
+One may want many different kind of information to be communicated from the
+compiler back to the user, whether via an IDE, language server or directly in a
+terminal, such as:
+
+* Errors and Warnings
+* Code Actions / Quick Fixes, Refactorings
+* Semantic (symbol) search, showing results
+* Showing symbol types, function argument types, code suggestions
+* List of functions and symbols in a file
+* Anything else an IDE would want
+* Language Server
+* ...
+
+Even in just a terminal usage one can imagine asking the compiler to do any of
+the above, such as finding all places where a symbol is used in a particular
+way. One can also imagine the compiler giving hints, help and suggestions, such
+as suggestions for refactoring, or writing something a certain way.
+
+One might design message types for all of the above, even in a terminal, and
+also for an IDE as a language server.
+
+In the most limited form, when the code is just being compiled noninteractively
+in a terminal, we typically want the compiler to just print errors and
+warnings. Errors must be fixed, and the goal for warnings is to enable strict
+warnings and ensure the code builds cleanly (warning free). One can have
+different levels/modes of warnings, from least strict to most strict and only
+ensure the code builds cleanly at a certain level of warnings.
+
+# Anatomy of an Error Message
+
+The error message contains the following information.
+
+One line (short) description (perhaps less than ~65 characters): sort of like
+the first line in a git commit message.
+
+Primary error label: which contains one ore more code spans and an optional
+short message/label attached to the spans. In some rare cases there can also be
+more than one primary error labels. Explains briefly but clearly what happened.
+
+A code span is an interval in some file, so it contains a filename, beginning
+line+column and ending line+column.
+
+Optional: long description. One or more paragraphs explaining what the error
+is, why it happens in general and what the options are to fix it, with
+examples. Similar to `rustc --explain` (not code specific) or Elm's error
+messages (which can be code specific, for example listing the types in the
+actual code).
+
+Optional: secondary error labels. Each label contains one or more spans, and an
+optional message/label attached to the spans. Explains briefly but clearly why
+the error happened.
+
+Optional: the error message can have children. The children can be of type help
+or note. Each contains an (optional?) one line description and an optional
+primary and/or secondary labels. Can contain long description too.
+
+# Anatomy of a Warning Message
+
+It seems it is similar to an error message. But the primary warning label does
+not need a message, can just be a span. The children can be "help" which can
+have a primary label with a message; if the span is identical to the parent's
+primary, then the message "help: ..." ends up being attached to it.
+
+# Rendering
+
+Each error or warning message is rendered separately.
+
+For a given message, the parent and children get all rendered at once. If some
+spans (across the parent's and all children's labels) are identical and both
+primary or both secondary, then they get merged. Identical lines get merged. If
+spans overlap (whether of the same or different type), then they get rendered
+using some scheme. All the information gets rendered in some consistent manner.
+
+One can think of it as having an IDE with the source code, and it gets
+annotated with all the primary and secondary labels from the parent and
+children, and then the short and long description from the parent and children
+gets appended at the bottom in some way. A short description from a child can
+also get appended as a label if the label does not have a message.
+
+The code is shown using the following algorithm: all spans are collected as a
+union. As a whole, they point to one or more files. All such files are shown.
+In each file, all lines that any span points to are shown. If the spans are
+close together, the lines between them (with no span) can also be shown. One
+can also show a few lines before and after for context, sort of like a "git
+diff".
+
+## Levels of Rendering
+
+There are several rendering styles, all in wide use. They depend on personal
+taste and the target audience. The error rendering should thus be configurable
+with a command line option such as `--error-style=short`.
+
+### Short (minimal)
+
+Just take the parent and primary label. Show primary label's filename+ first
+line number, and optionally first column; show parent's short description.
+
+    myfile.f90:45: error: use of undeclared identifier 'x10'
+
+or:
+
+    myfile.f90:45:7 error: use of undeclared identifier 'x10'
+
+Optionally: show the line, either with just the start location (^), or the
+whole span (^^^^^^ or ^~~~~~~).
+
+    myfile.f90:45:7 error: use of undeclared identifier 'x10'
+    y = 4+x10
+          ^
+
+or:
+
+    myfile.f90:45:7 error: use of undeclared identifier 'x10'
+    y = 4+x10
+          ^^^
+
+or
+
+    myfile.f90:45:7 error: use of undeclared identifier 'x10'
+    y = 4+x10
+          ^~~
+
+Optional colors: The error can red, the short description can be bold, the code
+is in black and the ^ and ~ markers can be red or green.
+
+### Detailed
+
+Shows everything except long descriptions: shows primary and secondary labels
+with messages and all children.
+
+    semantic error: Symbol is already declared in the same scope
+     --> tests/errors/redeclaration1.f90:4:12
+      |
+    3 | integer :: idx1
+      |            ~~~~ original declaration
+    4 | real :: j, idx1
+      |            ^^^^ redeclaration
+      = note: ...
+      = help: ...
+
+### Full
+
+The same as detailed but also shows long description.
+
+### More verbose style
+
+One can number the labels with (1), (2), ... and then reference them from a
+prose. The prose can contain some code specific information such as actual
+types versus expected types, explaining in regular sentences what went wrong,
+why and options to fix it.
\ No newline at end of file