#929: test functions doc #751: improved function documentation (#930)

devonfw · Oct 7, 2022 · 7874acf · 7874acf
1 parent a928e96
commit 7874acf
Show file tree

Hide file tree

Showing 35 changed files with 176 additions and 96 deletions.
diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
@@ -7,6 +7,7 @@ This file documents all notable changes to https://github.com/devonfw/ide[devonf
 New release with various improvements and bugfixes:
 
 * https://github.com/devonfw/ide/issues/826[#826]: List available versions for a tool
+* https://github.com/devonfw/ide/issues/929[#929]: Ensure function documentation is in sync
 
 The full list of changes for this release can be found in https://github.com/devonfw/ide/milestone/34?closed=1[milestone 2022.08.004].
 

diff --git a/documentation/DoD.asciidoc b/documentation/DoD.asciidoc
@@ -31,3 +31,4 @@ However, chances to get your change merged quickly are higher if you address all
 ** [ ] The new commandlet installs potential dependencies automatically (e.g. `doDevonCommand «required-other-tool» setup silent`).
 ** [ ] The variable `«TOOL»_VERSION` is honored by your commandlet so if present that version will be downloaded and installed.
 ** [ ] The new commandlet is tested on all plattforms it is availible for. Assuming you are using Windows, testing for Linux can be done with the Windows Subsystem for Linux and for MacOS we have a virtual cloud instance.
+* [ ] In case your PR adds, changes, or removes a function (in `functions` or `environment-project`) you need to update `functions.asciidoc` accordingly. There is an automated test that will fail otherwise.
diff --git a/documentation/functions.asciidoc b/documentation/functions.asciidoc
diff --git a/scripts/src/main/resources/scripts/functions b/scripts/src/main/resources/scripts/functions
@@ -305,7 +305,7 @@ function doLicenseAgreement() {
     if doIsBatch
     then
       doFail "You need to accept these terms of use and all license agreements. Please rerun in interactive (non-batch) mode."
-    fi    
+    fi
     if doAskToContinue "Do you accept these terms of use and all license agreements?" "return"
     then
       echo -e "On $(date +"%Y-%m-%d") at $(date +"%H:%M:%S") you accepted the devonfw-ide License.\nhttps://github.com/devonfw/ide/blob/master/documentation/LICENSE.asciidoc" > "${DEVON_HOME_DIR}/.devon/.license.agreement"      
@@ -376,7 +376,7 @@ function doDevonCommandAndReturn() {
       doError "Command '${command_name} ${*}' failed with exit code ${result}"
       return ${result}
     fi
-  fi  
+  fi
 }
 
 # $1: the URL to download

diff --git a/scripts/src/test/bash/test-functions → scripts/src/test/bash/functions-test b/scripts/src/test/bash/test-functions → scripts/src/test/bash/functions-test
diff --git a/scripts/src/test/bash/integration-test-aws b/scripts/src/test/bash/integration-test-aws
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest aws
diff --git a/scripts/src/test/bash/integration-test-az b/scripts/src/test/bash/integration-test-az
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest az
diff --git a/scripts/src/test/bash/integration-test-cobigen b/scripts/src/test/bash/integration-test-cobigen
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest cobigen
diff --git a/scripts/src/test/bash/integration-test-docker b/scripts/src/test/bash/integration-test-docker
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest docker
diff --git a/scripts/src/test/bash/integration-test-dotnet b/scripts/src/test/bash/integration-test-dotnet
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest dotnet
diff --git a/scripts/src/test/bash/integration-test-eclipse b/scripts/src/test/bash/integration-test-eclipse
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest eclipse
diff --git a/scripts/src/test/bash/integration-test-gcviewer b/scripts/src/test/bash/integration-test-gcviewer
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest gcviewer
diff --git a/scripts/src/test/bash/integration-test-gh b/scripts/src/test/bash/integration-test-gh
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest gh
diff --git a/scripts/src/test/bash/integration-test-graalvm b/scripts/src/test/bash/integration-test-graalvm
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest graalvm
diff --git a/scripts/src/test/bash/integration-test-gradle b/scripts/src/test/bash/integration-test-gradle
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest gradle
diff --git a/scripts/src/test/bash/integration-test-helm b/scripts/src/test/bash/integration-test-helm
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest helm
diff --git a/scripts/src/test/bash/integration-test-intellij b/scripts/src/test/bash/integration-test-intellij
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest intellij
diff --git a/scripts/src/test/bash/integration-test-ionic b/scripts/src/test/bash/integration-test-ionic
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest ionic
diff --git a/scripts/src/test/bash/integration-test-jasypt b/scripts/src/test/bash/integration-test-jasypt
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest jasypt
diff --git a/scripts/src/test/bash/integration-test-java b/scripts/src/test/bash/integration-test-java
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest java
diff --git a/scripts/src/test/bash/integration-test-jenkins b/scripts/src/test/bash/integration-test-jenkins
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest jenkins
diff --git a/scripts/src/test/bash/integration-test-kubectl b/scripts/src/test/bash/integration-test-kubectl
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest kuberctl
diff --git a/scripts/src/test/bash/integration-test-lazydocker b/scripts/src/test/bash/integration-test-lazydocker
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest lazydocker
diff --git a/scripts/src/test/bash/integration-test-mvn b/scripts/src/test/bash/integration-test-mvn
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest mvn
diff --git a/scripts/src/test/bash/integration-test-ng b/scripts/src/test/bash/integration-test-ng
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest ng
diff --git a/scripts/src/test/bash/integration-test-node b/scripts/src/test/bash/integration-test-node
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest node
diff --git a/scripts/src/test/bash/integration-test-npm b/scripts/src/test/bash/integration-test-npm
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest npm
diff --git a/scripts/src/test/bash/integration-test-oc b/scripts/src/test/bash/integration-test-oc
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest oc
diff --git a/scripts/src/test/bash/integration-test-pip b/scripts/src/test/bash/integration-test-pip
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest pip
diff --git a/scripts/src/test/bash/integration-test-python b/scripts/src/test/bash/integration-test-python
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest python
diff --git a/scripts/src/test/bash/integration-test-sonar b/scripts/src/test/bash/integration-test-sonar
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest sonar
diff --git a/scripts/src/test/bash/integration-test-terraform b/scripts/src/test/bash/integration-test-terraform
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest terraform
diff --git a/scripts/src/test/bash/integration-test-vscode b/scripts/src/test/bash/integration-test-vscode
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest vscode
diff --git a/scripts/src/test/bash/integration-test-yarn b/scripts/src/test/bash/integration-test-yarn
@@ -1,4 +1,4 @@
 #!/bin/bash
 
-source "$(dirname "${0}")"/test-functions
+source "$(dirname "${0}")"/functions-test
 doCommandTest yarn
diff --git a/scripts/src/test/bash/test-functions-doc b/scripts/src/test/bash/test-functions-doc
@@ -0,0 +1,16 @@
+#!/bin/bash
+
+SCRIPTS_PATH="../../../../scripts/src/main/resources/scripts"
+( set -o pipefail; grep "function " "${SCRIPTS_PATH}/functions" "${SCRIPTS_PATH}/environment-project" | sed 's/.*function //' | sed 's/() {//' | sort -u > functions.list ) || exit 1
+( set -o pipefail; grep "=== " "../../../../documentation/functions.asciidoc"  | sed 's/=== //' | sort -u > functions.adoc.list ) || exit 1
+
+diff functions.list functions.adoc.list
+if [ "$?" = 0 ]
+then
+  echo "Documentation of functions and function declarations are in sync."
+  echo "Awesome!"
+else
+  echo "Documentation of functions does not match function declarations!"
+  echo "Please keep function documentation and declarations in sync!"
+  exit 1
+fi