Document meanings of message severities

[MeAmAnUsername]

Summary
Document the meanings, causes, fixes and use cases of message severities

Todo

• Decide where to add
• Write documentation
  • Include a link to the documentation for Compiler option: treat warnings as errors #158 if that has been implemented already. Also include a link there back to this documentation.

Reason
The severity of messages in PIE have meaning, but this is not documented anywhere. If it is, users can learn about it and use it to their advantage and report when something is inconsistent. Future PIE maintainers/developers know to maintain the meanings and can use it as a guide for the severity of new messages.

Description
Message severities in PIE have different meanings, causes for the message, possible fixes, and use cases.

• Error
  Meaning: Cannot compile/analyze this code.
  Cause: there are currently two possible causes for this severity:

  • User error: it is unclear what the static or runtime semantics for this code are.
  • This feature has not been implemented yet (e.g. Generate code for type parameterized tasks #181)

  Fix: this code should be changed before it can be compiled.
  Use case: a developer makes a mistake while coding.

• Warning
  Meaning: the semantics for this code are clear and it can be compiled, but it is clearly not the best way to express this.
  Cause: code that can be expressed more clearly, e.g. useless imports, no-ops.
  Fix: a warning is always fixable, i.e. can be replaced with equivalent but cleaner code. Ideally, the warning states what that cleaner code is. It would be nice if the warning has a quick fix to apply the suggestion.
  Use case: warnings are fine while developing code, but should be fixed before finishing the code. Can be enforced by treating warnings as errors (see Compiler option: treat warnings as errors #158) in the continuous integration of your main branch.

• Note
  Meaning: this code could be fine but seems fishy. Meant to bring something to the attention of the developer, in other words, to note it.
  Cause: code that is likely a mistake, but might be intended.
  Fix: developers can change it if that makes the code better. If not, it is recommended to add a comment explaining why it is done this way. Ideally, notes explain what to do to remove the note.
  Use case: something which is almost always/often a mistake, but not always, and there are no better ways to express it in the cases where it is intended.

Possible locations where this could be documented:

• Reference documentation, in its own page or on the introduction page.
• Background
• On the page with explanations for messages, see Add list with explanations of editor messages #281

Related issues

• Use case of warnings: Compiler option: treat warnings as errors #158
• Possible location to put this documentation: Add list with explanations of editor messages #281