Bash functions style cleanup

+ Update rst documentation for bash style
 + Command substitution:
  + Clarify when to use backticks.
  + Recommend avoiding nested command substitution.
  + Do not recommend putting command substitution results into quotes.
 + Function definition content:
  + Move "set -exuo pipefail" after comment only blocks.
  + Other set flags allowed for functions with good reasons.
+ Apply the new recommendations.
 - Blank lines unified in code but no written recommendation in rst.
+ Add missing references to functions called, variables read or set.
 + Add TODOs to where lists would be long.
+ Minor improvements to function descriptions.
+ Make "if" expressions more python-like.
+ Add missing "|| die" (or "|| true") where spotted.
+ Downgrade DEFAULT_NIC to a local variable.
+ Add TODO to list reasons for blacklisted tags.

Change-Id: I05dce030a8c2cb1b3a242d8b977e8fe150d8ee20
Signed-off-by: Vratko Polak <vrpolak@cisco.com>

1 files changed, 21 insertions, 10 deletions

diff --git a/resources/libraries/bash/function/artifacts.sh b/resources/libraries/bash/function/artifacts.sh
index fc9c886a3b..fe755af9d9 100644
--- a/resources/libraries/bash/function/artifacts.sh
+++ b/resources/libraries/bash/function/artifacts.sh
@@ -17,12 +17,17 @@
 set -exuo pipefail
 
 function download_artifacts () {
-    # Get and/or install VPP artifacts from packagecloud.io.
+
+    # Download or install VPP artifacts from packagecloud.io.
     #
     # Variables read:
     # - CSIT_DIR - Path to existing root of local CSIT git repository.
     # Variables set:
     # - REPO_URL - FD.io Packagecloud repository.
+    # Functions conditionally called (see their documentation for side effects):
+    # - download_ubuntu_artifacts
+    # - download_centos_artifacts
+    # - download_opensuse_artifacts
 
     set -exuo pipefail
 
@@ -51,12 +56,14 @@ function download_artifacts () {
 }
 
 function download_ubuntu_artifacts () {
-    # Get and/or install Ubuntu VPP artifacts from packagecloud.io.
+
+    # Download or install Ubuntu VPP artifacts from packagecloud.io.
     #
     # Variables read:
     # - REPO_URL - FD.io Packagecloud repository.
     # - VPP_VERSION - VPP version.
-    # - INSTALL - If install packages or download only. Default: download
+    # - INSTALL - Whether install packages (if set to "true") or download only.
+    #             Default: "false".
 
     set -exuo pipefail
 
@@ -112,7 +119,7 @@ function download_ubuntu_artifacts () {
     done
     set -x
 
-    if [ "${INSTALL:-false}" = true ]; then
+    if [[ "${INSTALL:-false}" == "true" ]]; then
         sudo apt-get -y install "${artifacts[@]}" || {
             die "Install VPP artifacts failed."
         }
@@ -124,12 +131,14 @@ function download_ubuntu_artifacts () {
 }
 
 function download_centos_artifacts () {
-    # Get and/or install CentOS VPP artifacts from packagecloud.io.
+
+    # Download or install CentOS VPP artifacts from packagecloud.io.
     #
     # Variables read:
     # - REPO_URL - FD.io Packagecloud repository.
     # - VPP_VERSION - VPP version.
-    # - INSTALL - If install packages or download only. Default: download
+    # - INSTALL - Whether install packages (if set to "true") or download only.
+    #             Default: "false".
 
     set -exuo pipefail
 
@@ -145,7 +154,7 @@ function download_centos_artifacts () {
         artifacts+=(${packages[@]/%/-${VPP_VERSION-}})
     fi
 
-    if [ "${INSTALL:-false}" = true ]; then
+    if [[ "${INSTALL:-false}" == "true" ]]; then
         sudo yum -y install "${artifacts[@]}" || {
             die "Install VPP artifact failed."
         }
@@ -157,12 +166,14 @@ function download_centos_artifacts () {
 }
 
 function download_opensuse_artifacts () {
-    # Get and/or install OpenSuSE VPP artifacts from packagecloud.io.
+
+    # Download or install OpenSuSE VPP artifacts from packagecloud.io.
     #
     # Variables read:
     # - REPO_URL - FD.io Packagecloud repository.
     # - VPP_VERSION - VPP version.
-    # - INSTALL - If install packages or download only. Default: download
+    # - INSTALL - Whether install packages (if set to "true") or download only.
+    #             Default: "false".
 
     set -exuo pipefail
 
@@ -178,7 +189,7 @@ function download_opensuse_artifacts () {
         artifacts+=(${packages[@]/%/-${VPP_VERSION-}})
     fi
 
-    if [ "${INSTALL:-false}" = true ]; then
+    if [[ "${INSTALL:-false}" == "true" ]]; then
         sudo yum -y install "${artifacts[@]}" || {
             die "Install VPP artifact failed."
         }