Merge pull request github#11599 from igfoo/igfoo/diags

Java/Kotlin: Update the diagnostic severity documentation

Author: tamasvajk

java/ql/lib/semmle/code/java/Diagnostics.qll

@@ -15,8 +15,18 @@ class Diagnostic extends @diagnostic {
   string getGeneratedBy() { diagnostics(this, result, _, _, _, _, _) }
 
   /**
-   * Gets the severity of the message, on a range from 1 to 5: 1=remark,
-   * 2=warning, 3=discretionary error, 4=error, 5=catastrophic error.
+   * Gets the severity of the message.
+   *
+   * For Java, this ranges from 1 to 8:
+   * 1=warning(low)
+   * 2=warning(normal)
+   * 3=warning(high)
+   * 4=error(low)    Minor extractor errors, with minimal impact on analysis
+   * 5=error(normal) Most extractor errors, with local impact on analysis
+   * 6=error(high)   Errors from the frontend
+   * 7=error(severe) Severe extractor errors affecting a single source file
+   * 8=error(global) Severe extractor errors likely to affect multiple source files
+   * For Kotlin, only the "normal" warning and error severities are used.
    */
   int getSeverity() { diagnostics(this, _, result, _, _, _, _) }