From 0e881daba3616ae53beac356e90d2b120f7f58b4 Mon Sep 17 00:00:00 2001
From: Alexander Udalov <Alexander.Udalov@jetbrains.com>
Date: Thu, 16 Jun 2016 18:38:16 +0300
Subject: [PATCH] Update diagnostic tests ReadMe, explain tests with diagnostic
 arguments

---
 compiler/testData/diagnostics/ReadMe.md | 30 +++++++++++++++++++------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/compiler/testData/diagnostics/ReadMe.md b/compiler/testData/diagnostics/ReadMe.md
index c2c21ca5201..cec9ce67785 100644
--- a/compiler/testData/diagnostics/ReadMe.md
+++ b/compiler/testData/diagnostics/ReadMe.md
@@ -1,12 +1,29 @@
-Several directives can be added in the beginning of a test file in the syntax:
+# Diagnostic tests format specification
 
-`// !DIRECTIVE`
+Each diagnostic test consists of a single .kt file containing the code of one or several Kotlin or Java source files.
+Each diagnostic, be it a warning or an error, is marked in the following way:
 
-## Directives:
+    <!DIAGNOSTIC_FACTORY_NAME!>element<!>
+
+where `DIAGNOSTIC_FACTORY_NAME` is the name of the diagnostic which is usually one of the constants in one of `Errors*` classes.
+
+To test not only the presence of the diagnostic but also the arguments which will be rendered to the user, provide string representations of all of them in the parentheses delimited with `;` after the diagnostic name:
+
+    return <!TYPE_MISMATCH(String; Nothing)!>"OK"<!>
+
+Note: if you're unsure what text should be added for the parameters, just leave the parentheses empty and the failed test will present the actual values in the assertion message.
+
+## Directives
+
+Several directives can be added to the beginning of a test file with the following syntax:
+
+    // !DIRECTIVE
 
 ### 1. DIAGNOSTICS
 
-Must be
+This directive allows to exclude some irrelevant diagnostics (e.g. unused parameter) from a certain test, or to test only a specific set of diagnostics.
+
+The syntax is
 
     '([ + - ! ] DIAGNOSTIC_FACTORY_NAME | ERROR | WARNING | INFO ) +'
 
@@ -18,7 +35,7 @@ Must be
 
   Directives are applied in the order of appearance, i.e. `!FOO +BAR` means include only `FOO` and `BAR`.
 
-#### Examples:
+#### Usage:
 
     // !DIAGNOSTICS: -WARNING +CAST_NEVER_SUCCEEDS
 
@@ -59,8 +76,7 @@ The directive lets you compose a test consisting of several files in one actual
 
 ### 4. LANGUAGE
 
-This directive lets you enable or disable certain language features. Language features are named as
-enum entries of the class LanguageFeature. Each feature can be enabled with `+` or disabled with `-`.
+This directive lets you enable or disable certain language features. Language features are named as enum entries of the class `LanguageFeature`. Each feature can be enabled with `+` or disabled with `-`.
 
 #### Usage: