add explanation to examples of AssertClassRule (#314)

Author: jmgrassau

com.sap.adt.abapcleaner/src/com/sap/adt/abapcleaner/rules/commands/AssertClassRule.java

@@ -56,6 +56,21 @@ public String getExample() {
       return "" 
       	+ LINE_SEP + "CLASS cl_product_code IMPLEMENTATION."
 			+ LINE_SEP + "  METHOD use_assert_class." 
+			+ LINE_SEP + "    \" Explanation: Using ASSERT in product code is discouraged, because it immediately dumps, even when the code" 
+			+ LINE_SEP + "    \" is called from a test. You can therefore only test the 'happy' cases. This is unsatisfactory, because for" 
+			+ LINE_SEP + "    \" code to be clean and testable, you should be able to safeguard that assertions work correctly in unhappy cases." 
+			+ LINE_SEP + "    " 
+			+ LINE_SEP + "    \" The solution is to not use ASSERT in product code, but to rather call a 'productive' assert class cx_XYZ_assert," 
+			+ LINE_SEP + "    \" which has methods just like CL_ABAP_UNIT_ASSERT to check your expectations, but is specific to your solution XYZ." 
+			+ LINE_SEP + "    \" With that, even the 'unhappy' cases can be tested, because your tests can catch cx_XYZ_assert exceptions and" 
+			+ LINE_SEP + "    \" ensure they are raised when they should." 
+			+ LINE_SEP + "    " 
+			+ LINE_SEP + "    \" Once you have created such a class (short example see below), this cleanup rule helps to automatically convert" 
+			+ LINE_SEP + "    \" existing ASSERT statements into static cx_XYZ_assert=>...( ) calls. Since the exact desired behavior of the" 
+			+ LINE_SEP + "    \" cx_XYZ_assert class may depend on your solution, the class name is not fixed, but can be configured above." 
+			+ LINE_SEP + "    \" To exclude accidental use of this rule, this cleanup rule is intentionally deactivated at first, and the" 
+			+ LINE_SEP + "    \" class cx_assert does not exist, but must first be adjusted to your own implementation."
+			+ LINE_SEP 
 			+ LINE_SEP + "    ASSERT lo_instance IS BOUND." 
 			+ LINE_SEP + "    ASSERT is_any_structure-component IS NOT BOUND." 
 			+ LINE_SEP