diff --git a/platform/util/src/com/intellij/util/xmlb/annotations/OptionTag.java b/platform/util/src/com/intellij/util/xmlb/annotations/OptionTag.java
index 5147e0603439..dac87e811ba2 100644
--- a/platform/util/src/com/intellij/util/xmlb/annotations/OptionTag.java
+++ b/platform/util/src/com/intellij/util/xmlb/annotations/OptionTag.java
@@ -1,18 +1,4 @@
-/*
- * Copyright 2000-2014 JetBrains s.r.o.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+// Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
 package com.intellij.util.xmlb.annotations;
 
 import com.intellij.util.xmlb.Constants;
@@ -24,8 +10,6 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Please consider to use annotation parameters only to achieve backward compatibility. Otherwise feel free to file issues about serialization cosmetics.
- *
  * <p>Store value in tag like {@code <option name="optionName" value="optionValue"/>}</p>
  * <p>nameAttribute can be empty, in which case it is skipped: {@code <option value="optionValue" />}</p>
  *
diff --git a/platform/util/src/com/intellij/util/xmlb/annotations/XCollection.java b/platform/util/src/com/intellij/util/xmlb/annotations/XCollection.java
index cc7d503be5ad..3a59bbd14ca8 100644
--- a/platform/util/src/com/intellij/util/xmlb/annotations/XCollection.java
+++ b/platform/util/src/com/intellij/util/xmlb/annotations/XCollection.java
@@ -8,44 +8,22 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/**
- * ```xml
- * <option value="$value" />
- * ... n item elements
- * ```
- *
- * Where `option` it is item element (use `elementName` to customize element name) and
- * `value` it is value attribute (use `valueAttributeName` to customize attribute name).
- */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.METHOD})
 public @interface XCollection {
   /**
-   * The property element name. Defaults to property name if `style = v2`.
-   * If not specified and `style` is not specified — property serialized using option tag.
+   * The property element name. Defaults to property name if {@link #style} is set to {@link Style#v2}.
+   * If not specified and {@link #style} is not specified — property serialized using option tag.
    */
   String propertyElementName() default "";
 
   /**
-   * Value of primitive type wrapped into element named `option`. This option allows you to customize element name.
-   * For example, for `elementName = "module"`:
-   *
-   * <module value="$value" />
+   * Value of primitive type wrapped into element named {@code option}. This option allows you to customize element name.
    */
   String elementName() default Constants.OPTION;
 
   /**
    * Value of primitive type wrapped into element named `option`. This option allows you to customize name of value attribute.
-   * For example, for `valueAttributeName = "name"`:
-   *
-   * <option name="$value" />
-   *
-   * Empty name is allowed — in this case value will be serialized as element text.
-   * For example, for `valueAttributeName = ""`:
-   *
-   * <option>
-   *   $value
-   * </option>
    */
   String valueAttributeName() default Constants.VALUE;
 
diff --git a/platform/util/src/com/intellij/util/xmlb/annotations/XMap.java b/platform/util/src/com/intellij/util/xmlb/annotations/XMap.java
index d58b61b1a886..598f30b71ca6 100644
--- a/platform/util/src/com/intellij/util/xmlb/annotations/XMap.java
+++ b/platform/util/src/com/intellij/util/xmlb/annotations/XMap.java
@@ -8,15 +8,6 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/**
- * ```xml
- * <option value="$value" />
- * ... n item elements
- * ```
- *
- * Where `option` it is item element (use `elementName` to customize element name) and
- * `value` it is value attribute (use `valueAttributeName` to customize attribute name).
- */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.TYPE, ElementType.METHOD})
 public @interface XMap {
diff --git a/platform/util/src/com/intellij/util/xmlb/annotations/readme.md b/platform/util/src/com/intellij/util/xmlb/annotations/readme.md
new file mode 100644
index 000000000000..8612b4509d13
--- /dev/null
+++ b/platform/util/src/com/intellij/util/xmlb/annotations/readme.md
@@ -0,0 +1,73 @@
+Please consider to use annotation parameters only to achieve backward compatibility. Otherwise feel free to file issues about serialization cosmetics.
+
+## Lists and Sets
+
+`XCollection` annotation intended to customize list and set serialization.
+
+Two styles are provided:
+
+* `v1`:
+  ```xml
+  <option name="propertyName">
+    <option value="value1" />
+    <option value="valueN" />
+  </option>
+  ```
+    
+* `v2`:
+  ```xml
+  <propertyName>
+    <option value="$value" />
+  </propertyName>
+  ```
+
+Where second-level `option` it is item element (use `elementName` to customize element name) and
+`value` it is value attribute (use `valueAttributeName` to customize attribute name).
+
+Because of backward compatibility, `v1` style is used by default. In the examples `v2` style is used.
+
+### Custom List Item Value Attribute Name
+
+Value of primitive type wrapped into element named `option`. `valueAttributeName` allows you to customize name of value attribute.
+
+Empty name is allowed — in this case value will be serialized as element text.
+
+* `valueAttributeName = "name"`
+  ```xml
+  <propertyName>
+    <option name="$value1" />
+    <option name="$valueN" /> 
+  </propertyName>
+  ```
+* `valueAttributeName = ""`
+  ```xml
+  <propertyName>
+    <option>$value1</option>
+    <option>$valueN</option>
+  </propertyName>
+  ```
+
+## Maps
+
+`XMap` annotation intended to customize map serialization and to enable new serialization format.
+
+* With `XMap` annotation:
+  ```xml
+  <propertyName>
+    <entry key="key1" value="value1" />
+    <entry key="keyN" value="valueN" />
+  </propertyName>
+  ```
+  
+* Without `XMap` annotation:
+  ```xml
+  <option name="propertyName">
+    <map>
+      <entry key="key1" value="value1" />
+      <entry key="keyN" value="valueN" />
+    </map>
+  </option>
+  ```
+  
+So, it is recommended to always specify `XMap` annotation.
+  
\ No newline at end of file