Add actions for doxygen build and spell-check. Test doxygen build fro…

…m workflow

.github/workflows/test.yml

@@ -32,3 +32,16 @@ jobs:
         uses: ./complexity
         with:
           path: coreMQTT
+  test-doxygen-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/checkout@v2
+        with:
+          repository: FreeRTOS/coreMQTT
+          ref: main
+          path: coreMQTT
+      - name: Test doxygen build action
+        uses: ./doxygen
+        with:
+          path: coreMQTT

doxygen/action.yml

@@ -0,0 +1,22 @@
+name: 'doxygen'
+description: 'CI doxygen build check'
+inputs:
+  path:
+    description: 'Path to repository folder to run doxygen generation in.'
+    required: false
+    default: ./
+runs:
+  using: "composite"
+  steps:
+    - name: Install Doxygen
+      run: |
+        cd ${{ inputs.path }}
+        wget -qO- "http://doxygen.nl/files/doxygen-1.8.20.linux.bin.tar.gz" | sudo tar --strip-components=1 -xz -C /usr/local
+        sudo apt-get install -y libclang-9-dev
+      shell: bash
+    - name: Run Doxygen And Verify Stdout Is Empty
+      run: |
+        cd ${{ inputs.path }}
+        doxygen docs/doxygen/config.doxyfile 2>&1 | tee doxyoutput.txt
+        if [[ "$(wc -c < doxyoutput.txt | bc)" = "0" ]]; then exit 0; else exit 1; fi
+      shell: bash

spellings/action.yml

@@ -0,0 +1,27 @@
+name: 'spellings'
+description: 'CI spellings check'
+inputs:
+  path:
+    description: 'Path to repository folder to check spellings in.'
+    required: false
+    default: ./
+runs:
+  using: "composite"
+  steps:
+      - name: Install spell
+        run: |
+          sudo apt-get install spell
+          sudo apt-get install util-linux
+      - name: Check spelling
+        run: |
+          PATH=$PATH:$GITHUB_ACTION_PATH/tools
+          cd ${{ inputs.path }}
+          for lexfile in `find ./ -name lexicon.txt`
+          do dir=${lexfile%/lexicon.txt}
+            echo $dir
+            find-unknown-comment-words --directory $dir
+            if [ $? -ne "0" ]
+            then
+              exit 1
+            fi
+          done

spellings/tools/README.md

@@ -0,0 +1,31 @@
+# Pre-requisites to running the spell check scripts
+
+1. In your GNU environment, install the *spell* and *getopt* programs. Use the following commands in Debian distributions, to install the packages (*getopt* is part of the `util-linux` package):
+   ```shell
+   apt-get install spell
+   apt-get install util-linux
+   ```
+
+1. Add the folder containing the **tools/spell/ablexicon**, **tools/spell/extract-comments**, and **tools/spell/find-unknown-comment-words** scripts to your system's PATH.
+   ```shell
+   export PATH=<CSDK_ROOT>/tools/spell:$PATH
+   ```
+
+# How to create a lexicon.txt for a new library.
+
+1. Ensure there does not exist a file called "lexicon.txt" in your library's directory. Run the following command to create a lexicon.txt for your library:
+   ```shell
+   find-unknown-comment-words -d <CSDK_ROOT>/libraries/<LIBRARY_TYPE>/<MY_LIBRARY_NAME> > <CSDK_ROOT>/libraries/<LIBRARY_TYPE>/<MY_LIBRARY_NAME>/words.txt
+   mv <CSDK_ROOT>/libraries/<LIBRARY_TYPE>/<MY_LIBRARY_NAME>/words.txt <CSDK_ROOT>/libraries/<LIBRARY_TYPE>/<MY_LIBRARY_NAME>/lexicon.txt
+   ```
+
+1. Check the contents of *<CSDK_ROOT>/libraries/<LIBRARY_TYPE>/<MY_LIBRARY_NAME>/lexicon.txt* for any misspelled words. Fix them in your library's source code and delete them from the lexicon.txt.
+
+# How to run for changes to an existing library.
+
+1. If there exists a lexicon.txt in the library's directory, run the following command:
+   ```shell
+   find-unknown-comment-words -d <CSDK_ROOT>/libraries/<LIBRARY_TYPE>/<MY_LIBRARY_NAME>
+   ```
+
+1. Add any non-dictionary correctly spelled words to *<CSDK_ROOT>/libraries/<LIBRARY_TYPE>/<MY_LIBRARY_NAME>/lexicon.txt*. Fix any misspelled words in your code comment change.

spellings/tools/ablexicon

@@ -0,0 +1,96 @@
+#!/bin/bash
+#
+# ablexicon - Compare an input list of words against a dictionary and
+# optional lexicon.  If any words are in neither the dictionary nor the
+# lexicon, log them to stdout.
+#
+set -e
+set -f
+
+function usage () {
+    echo "Find occurrences of non-dictionary/lexicon words"
+    echo ""
+    echo "Usage:"
+    echo " ${0##*/} [options]"
+    echo ""
+    echo "Options:"
+    echo " -f, --file         source text (defaults to /dev/fd/0)"
+    echo " -l, --lexicon      lexicon file (one word per line)"
+    echo " -h, --help         display this help"
+    exit 1
+}
+
+#
+# Verify that required commands are present
+#
+REQUIRED=( "spell" "getopt" )
+for i in "${REQUIRED[@]}"
+do
+    command -v $i"" >/dev/null
+    if [ $? -ne "0" ]
+    then
+        echo "'"$i"' must be installed, exiting...">&2
+        exit 1
+    fi
+done
+
+GETOPT_OUT=`getopt -o hf:l: --long help,file:,lexicon: -n "${0##*/}" -- "$@"`
+if [ $? != 0 ]
+then
+    echo "Exiting..." >&2
+    exit 1
+fi
+
+eval set -- "$GETOPT_OUT"
+
+INFILE=/dev/fd/0
+LEXICON=/dev/null
+while true; do
+  case "$1" in
+    -h | --help ) usage $0 ;;
+    -f | --file ) INFILE="$2"; shift 2 ;;
+    -l | --lexicon ) LEXICON="$2"; shift 2 ;;
+    -- ) shift; break ;;
+    * ) break ;;
+  esac
+done
+
+if [ ! -f $INFILE"" ] && [ $INFILE"" != /dev/fd/0 ]
+then
+    echo "Invalid input file"
+    usage
+fi
+#
+# Read the lexicon into an array
+#
+readarray -t lexicon < $LEXICON""
+lexicon_size="${#lexicon[@]}"
+
+#
+# Search for all input words in the dictionary
+# and sort the output
+#
+for word in `cat $INFILE"" | spell | sort -u`
+do
+    #
+    # Search for each remaining word in the lexicon
+    #
+    found="false"
+    i="0"
+    while [[ "$i" -lt "$lexicon_size" ]] && [ "$found" == "false" ]
+    do
+        if [ "${lexicon[i]}" == "$word" ]
+        then
+            found="true"
+        fi
+        i=$((i+1))
+    done
+    if [ $found"" == "false" ]
+    then
+        #
+        # The word is neither in the dictionary nor the lexicon, send
+        # it to stdout.
+        #
+        echo $word
+    fi
+done

spellings/tools/extract-comments

@@ -0,0 +1,41 @@
+#!/bin/bash
+#
+# Extract comments from C/C++ files
+#
+set -e
+set -f
+
+function usage () {
+    echo "Extract comments from C/C++ files"
+    echo ""
+    echo "usage: "${0##*/}" file-list"
+    exit 1
+}
+
+if [ $# -lt 1 ]
+then
+	usage $0
+fi
+
+if [ $1 = "-h" ] || [ $1 == "--help" ]
+then
+    usage $0
+fi
+
+while test $# -gt 0
+do
+    if [ ! -f $1 ]
+    then
+        echo $0": '"$1"' is not a file." 2>/dev/null
+        exit 1
+    fi
+#
+# Extract all words from C/C++ language comments; add line
+# numbers to aid in searching.
+#
+# NOTE: This has some limitations.  For example, it prints
+# non-comment text at the beginning of a comment line.
+#
+    nl -ba $1 | awk '/\/\// {print $0}; /\/\*/ {comment=1}; {if(comment) print $0}; /\*\// {comment=0}'
+    shift
+done

spellings/tools/find-unknown-comment-words

@@ -0,0 +1,147 @@
+#!/bin/bash
+#
+# Locate unknown words in C/C++ comments.  Uses "extract-comments"
+# and "ablexicon" scripts.
+#
+set -o nounset
+set -o pipefail
+set -o errexit
+set -f
+
+BLUE="\e[1;34m"
+GREEN="\e[1;32m"
+DEFAULTFG="\e[39m"
+
+function usage () {
+    echo "Find unknown words in C/C++ comments"
+    echo ""
+    echo "Usage:"
+    echo " ${0##*/} [options]"
+    echo ""
+    echo "Options:"
+    echo " -d, --directory    directory to scan (defaults to .)"
+    echo " -l, --lexicon      lexicon file (one word per line, default 'lexicon.txt')"
+    echo " -t, --terse        terse output only (enabled if no lexicon available)"
+    echo " -h, --help         display this help"
+    exit 1
+}
+
+#
+# Verify that required commands are present
+#
+REQUIRED=( "extract-comments" "ablexicon" "getopt" )
+for i in "${REQUIRED[@]}"
+do
+    command -v $i"" >/dev/null
+    if [ $? -ne "0" ]
+    then
+        echo "Can't find '"$i"' , exiting...">&2
+        exit 1
+    fi
+done
+
+GETOPT_OUT=`getopt -o htd:l: --long help,terse,directory:,lexicon: -n "${0##*/}" -- "$@"`
+if [ $? != 0 ]
+then
+    echo "Exiting..." >&2
+    exit 1
+fi
+
+eval set -- "$GETOPT_OUT"
+
+DIRNAME=/dev/fd/0
+LEXICON=
+STATUS=
+TERSE=
+while true; do
+  case "$1" in
+    -h | --help ) usage $0 ;;
+    -t | --terse ) TERSE=1; shift ;;
+    -d | --directory ) DIRNAME="$2"; shift 2 ;;
+    -l | --lexicon ) LEXICON="$2"; shift 2 ;;
+    -- ) shift; break ;;
+    * ) break ;;
+  esac
+done
+
+if [ ! -d $DIRNAME"" ]
+then
+    echo "Invalid directory: "$DIRNAME
+    usage
+fi
+
+if [ $LEXICON"" = "" ]
+then
+    if [ -f $DIRNAME/lexicon.txt ]
+    then
+        LEXICON=$DIRNAME/lexicon.txt
+    else
+        LEXICON=/dev/null
+        TERSE=1
+    fi
+fi
+
+TMPFILE=${0##*/}-$USER-$RANDOM
+unknowns=( "not-used" )     # get around empty array with nounset
+extract-comments `find $DIRNAME \( -iname \*.[ch] -o -iname \*.dox \)` |
+    tr [:upper:] [:lower:] |
+    grep -o -E '[a-zA-Z]+' |
+    ablexicon -l $LEXICON > $TMPFILE
+readarray -O 1 -t unknowns < $TMPFILE
+rm -f $TMPFILE
+
+for word in "${unknowns[@]}"
+do
+    if [ $word"" == "not-used" ]
+	then
+        continue
+	fi
+
+    if [ $TERSE"" != "" ]
+    then
+        echo $word
+        continue
+    fi
+
+    for file in `find $DIRNAME \( -iname \*.[ch] -o -iname \*.dox \)`
+    do
+        if [[ $file == *"third_party"*  || $file == *"CMock"* ]]
+        then
+            continue
+        fi
+        # Disable errexit here, extract-comments can return non-zero
+        set +e
+        #
+        # A little inefficient here; we will grep twice, once to detect
+        # the unknown word and another to print it with color highlighting.
+        # If there's a way to preserve ANSI color output with the first
+        # search and reuse it within the if statement (I gave up trying
+        # to find one after a few minutes), that would be nice.
+        #
+        extract-comments $file | grep -iw $word > /dev/null
+        if [ $? == "0" ]
+        then
+            if [ $STATUS"" != "1"  ]
+            then
+                echo -e $GREEN"############################################################################"$DEFAULTFG
+                echo -e $GREEN"#"$DEFAULTFG
+                echo -e $GREEN"#  Unknown word(s) found.  Please either correct the spelling or add them"$DEFAULTFG
+                echo -e $GREEN"#  to the lexicon file '"$LEXICON"'".$DEFAULTFG
+                echo -e $GREEN"#"$DEFAULTFG
+                echo -e $GREEN"############################################################################"$DEFAULTFG
+                STATUS=1  # Return non-zero status if any unidentified words are found
+            fi
+            echo ""
+            echo -e $BLUE$file$DEFAULTFG
+            echo ""
+            extract-comments $file | grep --color=always -iw $word | GREP_COLORS="mt=01;32" grep --color=always -E -e '^[ \t]*[0-9]+'
+        fi
+        # Re-enable errexit
+        set -o errexit
+    done
+done
+
+if [ $STATUS"" = "1" ]
+then
+    exit 1
+fi