From 89fd30e84c40f46f2e300874a210fc2e41968c52 Mon Sep 17 00:00:00 2001
From: Marcus Holl <marcus.holl@sap.com>
Date: Fri, 1 Feb 2019 15:54:11 +0100
Subject: [PATCH] implement @see strategy

in case there is a pseudo annotation '@see' found in a step docu the docu is retrived from
the parameter with the same name in the other step. Format is:

'@see <OTHER_STEP_NAME>'

This simplifies documentation for parameters with same name and same
semantics used in more than one step.
---
 documentation/bin/createDocu.groovy | 33 +++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/documentation/bin/createDocu.groovy b/documentation/bin/createDocu.groovy
index b8ba84911..cfb272ea4 100644
--- a/documentation/bin/createDocu.groovy
+++ b/documentation/bin/createDocu.groovy
@@ -418,6 +418,19 @@ for (step in steps) {
     }
 }
 
+// replace @see tag in docu by docu from referenced step.
+for(step in stepDescriptors) {
+    if(step.value.parameters) {
+        for(param in step.value.parameters) {
+            if( param?.value?.docu?.contains('@see')) {
+                def otherStep = param.value.docu.replaceAll('@see', '').trim()
+                param.value.docu = fetchTextFrom(otherStep, param.key, stepDescriptors)
+                param.value.mandatory = fetchMandatoryFrom(otherStep, param.key, stepDescriptors)
+            }
+        }
+    }
+}
+
 for(step in stepDescriptors) {
     try {
         renderStep(step.key, step.value)
@@ -461,6 +474,26 @@ void renderStep(stepName, stepProperties) {
     theStepDocu.withWriter { w -> w.write text }
 }
 
+def fetchTextFrom(def step, def parameterName, def steps) {
+    try {
+        def docuFromOtherStep = steps[step]?.parameters[parameterName]?.docu
+        if(! docuFromOtherStep) throw new IllegalStateException("No docu found for parameter '${parameterName}' in step ${step}.")
+        return docuFromOtherStep
+    } catch(e) {
+        System.err << "[ERROR] Cannot retrieve docu for parameter ${parameterName} from step ${step}.\n"
+        throw e
+    }
+}
+
+def fetchMandatoryFrom(def step, def parameterName, def steps) {
+    try {
+        return steps[step]?.parameters[parameterName]?.mandatory
+    } catch(e) {
+        System.err << "[ERROR] Cannot retrieve docu for parameter ${parameterName} from step ${step}.\n"
+        throw e
+    }
+}
+
 def handleStep(stepName, prepareDefaultValuesStep, gse) {
 
     File theStep = new File(stepsDir, "${stepName}.groovy")