From be5e1e46c034126b56f82d4fe6304c3304bcd58b Mon Sep 17 00:00:00 2001
From: Jeremie Bresson <dev@jmini.fr>
Date: Mon, 28 Jan 2019 16:39:05 +0100
Subject: [PATCH 1/2] Document 'x-enum-descriptions' and 'x-enum-varnames'

---
 docs/templating.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/templating.md b/docs/templating.md
index 4246bdc327f7..f982fe95f8c6 100644
--- a/docs/templating.md
+++ b/docs/templating.md
@@ -615,6 +615,33 @@ For example, suppose you use your specification document for code generation wit
 
 The following are vendor extensions supported by OpenAPI Generator. The list may not be up-to-date, the best way is to look for "x-" in the built-in mustache templates.
 
+### All generators (core)
+
+#### Enum
+
+`x-enum-varnames` can be used to have an other enum name for the corresponding value. 
+`x-enum-descriptions` can be used to provide an individual description for each value.
+
+Example:
+
+```yaml
+WeatherType:
+  type: integer
+  format: int32
+  enum:
+    - 1
+    - 2
+    - 3
+  x-enum-descriptions:
+    - 'Blue sky'
+    - 'Slightly overcast'
+    - 'Take an umbrella with you'
+  x-enum-varnames:
+    - Sunny
+    - Cloudy
+    - Rainy
+```
+
 ### ObjC
 #### x-objc-operationId
 

From f6918eebd6c5f3a7e48ec7877e6029e09087ed81 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=A9mie=20Bresson?= <dev@jmini.fr>
Date: Tue, 29 Jan 2019 07:44:09 +0100
Subject: [PATCH 2/2] Update templating.md

---
 docs/templating.md | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/docs/templating.md b/docs/templating.md
index f982fe95f8c6..2d9eb8102874 100644
--- a/docs/templating.md
+++ b/docs/templating.md
@@ -619,8 +619,14 @@ The following are vendor extensions supported by OpenAPI Generator. The list may
 
 #### Enum
 
-`x-enum-varnames` can be used to have an other enum name for the corresponding value. 
+`x-enum-varnames` can be used to have an other enum name for the corresponding value.
+This is used to define names of the enum items.
+
 `x-enum-descriptions` can be used to provide an individual description for each value.
+This is used for comments in the code (like javadoc if the target language is java).
+
+`x-enum-descriptions` and `x-enum-varnames` are each expected to be list of items containing the same number of items as `enum`.
+The order of the items in the list matters: their position is used to group them together.
 
 Example:
 
@@ -629,9 +635,9 @@ WeatherType:
   type: integer
   format: int32
   enum:
-    - 1
-    - 2
-    - 3
+    - 42
+    - 18
+    - 56
   x-enum-descriptions:
     - 'Blue sky'
     - 'Slightly overcast'
@@ -642,6 +648,8 @@ WeatherType:
     - Rainy
 ```
 
+In the example for the integer value `42`, the description will be `Blue sky` and the name of the enum item will be `Sunny` (some generators changes it to `SUNNY` to respect some coding convention).
+
 ### ObjC
 #### x-objc-operationId