Adding spellcheck to the API docs and fix various typos found (#31)

* Adding spellcheck to the API docs and fix various typos found

* fix license marking

* Run spellcheck in CI job

* update gitignore

Author: BrianSipos

.github/workflows/docs.yaml

@@ -42,17 +42,21 @@ jobs:
           submodules: recursive
       - name: Set up OS
         run: |
-          sudo apt-get update && sudo apt-get install -y \
-            cmake ninja-build ruby build-essential \
-            libssl-dev libjansson-dev \
-            doxygen graphviz plantuml texlive texlive-latex-extra dblatex
+          sudo rm /var/lib/man-db/auto-update
+          sudo apt-get update
+          sudo apt-get install -y \
+              cmake ninja-build ruby build-essential \
+              libssl-dev libjansson-dev \
+              doxygen graphviz plantuml \
+              dblatex texlive texlive-latex-extra texlive-font-utils \
+              xmlstarlet aspell
       - name: Dependency build
         run: ./build.sh deps
       - name: Prep
         run: ./build.sh prep -DBUILD_TESTING=OFF -DTEST_MEMCHECK=OFF -DTEST_COVERAGE=OFF -DBUILD_DOCS_API=ON
       - name: Build
         run: |
-          ./build.sh --target docs-api-html docs-api-pdf
+          ./build.sh --target docs-api-html docs-api-pdf docs-api-misspelling
           ./build.sh install --component docs-api
       - name: Compress
         working-directory: testroot/usr/share/doc/bsl

.gitignore

@@ -6,10 +6,10 @@
 .pydevproject
 
 # Build files
-deps/build
-build
-testroot
+/deps/build
+/build/
+/testroot/
+/venv/
 __pycache__
-/.pytest_cache/
-venv/
+.pytest_cache/
 mock-bpa-test/ccsds_bpsec_redbook_draft_734.5-R-2_requirements_implementation_guide.yaml

docs/api/CMakeLists.txt

@@ -19,8 +19,14 @@ Institute of Technology, sponsored by the United States Government under
 the prime contract 80NM0018D0004 between the Caltech and NASA under
 subcontract 1700763.
 ]]
+
+include(GNUInstallDirs)
+
 find_package(Doxygen REQUIRED)
 
+find_program(XMLSTARLET_EXECUTABLE xmlstarlet)
+find_program(ASPELL_EXECUTABLE aspell)
+
 find_program(MAKE_EXECUTABLE make)
 message(STATUS "Found make at ${MAKE_EXECUTABLE}")
 find_program(DBLATEX_EXECUTABLE dblatex)
@@ -36,12 +42,15 @@ endif(PLANTUML_JAR)
 
 configure_file(Doxyfile.in Doxyfile @ONLY)
 
+set(XML_COMBINE ${CMAKE_CURRENT_BINARY_DIR}/xml/combine.xslt)
+set(XML_INDEX ${CMAKE_CURRENT_BINARY_DIR}/xml/index.xml)
 add_custom_target(
     docs-api-html
     BYPRODUCTS
         ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
         ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.tex
         ${CMAKE_CURRENT_BINARY_DIR}/latex/Makefile
+        ${XML_COMBINE} ${XML_INDEX}
     DEPENDS
         ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
         ${CMAKE_CURRENT_SOURCE_DIR}/footer.html
@@ -64,6 +73,38 @@ install(
     COMPONENT docs-api
 )
 
+if(XMLSTARLET_EXECUTABLE AND ASPELL_EXECUTABLE)
+    # spellcheck on combined XML output
+    set(DICTIONARY_TXT "${CMAKE_CURRENT_SOURCE_DIR}/dictionary.txt")
+    set(SPELLCHECK_XSL "${CMAKE_CURRENT_SOURCE_DIR}/spellcheck.xsl")
+    set(MISSPELLING_TXT "misspelling.txt")
+    add_custom_command(
+        OUTPUT "dictionary.cwl"
+        DEPENDS ${DICTIONARY_TXT}
+        COMMAND cat "${DICTIONARY_TXT}" |
+            ${ASPELL_EXECUTABLE} --lang=en create master "./dictionary.cwl"
+    )
+    add_custom_command(
+        OUTPUT ${MISSPELLING_TXT}
+        DEPENDS
+            ${XML_COMBINE} ${XML_INDEX}
+            ${SPELLCHECK_XSL} "dictionary.cwl"
+        COMMAND
+            ${XMLSTARLET_EXECUTABLE} tr "${XML_COMBINE}" "${XML_INDEX}" |
+            ${XMLSTARLET_EXECUTABLE} tr "${SPELLCHECK_XSL}" |
+            ${ASPELL_EXECUTABLE} --mode=html --lang=EN_US --extra-dicts=./dictionary.cwl list |
+            sort | uniq > "${MISSPELLING_TXT}"
+    )
+    add_custom_target(
+        docs-api-misspelling ALL
+        DEPENDS "${MISSPELLING_TXT}"
+        COMMAND cat "${MISSPELLING_TXT}"
+        # success means file is present and empty
+        COMMAND test -f "${MISSPELLING_TXT}" -a ! -s "${MISSPELLING_TXT}"
+        COMMENT "Checking ${MISSPELLING_TXT}"
+    )
+endif(XMLSTARLET_EXECUTABLE AND ASPELL_EXECUTABLE)
+
 if(MAKE_EXECUTABLE AND DBLATEX_EXECUTABLE)
     add_custom_target(
         docs-api-pdf

docs/api/Developer_Guide.md

@@ -44,9 +44,9 @@ Generally, functions returning `int`s indicate error codes.
  * A negative number ALWAYS indicates an error.
  * A positive number can be something else depending on context.
 
-## Enums
+## Enumerations
 
-Enums take the format of `BSL_EnumName_e` (with a typedef).
+Enumerations take the format of `BSL_EnumName_e` (with a typedef).
 
 Variants of the enum should be "namespaced" with the enum, to manage clutter.
 
@@ -74,7 +74,7 @@ More notes forthcoming.
  * A NULL pointer for almost any function argument is considered an anomaly and a programmer-error.
  * Note the \@nullable doxygen command to indicate whenever a parameter _may_ be NULL.
  * The public front-end API is more gracious to NULL arguments (returns error code). It is considered a runtime anomaly.
- * Code further in the backend is more `assert`-ive of NULL checks. A NULL argument here is not a runtime anomaly, but rather an indication the programmer made a mistake.
+ * Code further in the backend performs more `assert` checking for NULL values. A NULL argument here is not a runtime anomaly, but rather an indication the programmer made a mistake.
  * If you are not already familiar, see the ["Billion Dollar Mistake"](https://www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/).
  * \*Note: The `GetBlockMetadata` function does permit NULL arguments, as it only populates arguments that are requested.
  * \*Note: Certain functions that wrap OpenSSL functionality may also permit NULLs to be consistent with its interface.
@@ -104,7 +104,7 @@ More notes forthcoming.
  * Third party libraries providing containers may be more hassle and risk than they are worth.
 
 #### » M\*Lib structures should not be referenced in the Frontend API
- * Keep M\*Lib usage to the BSL backend, and use standard/primative structs for frontend API. The frontend should not include any M\*Lib headers.
+ * Keep M\*Lib usage to the BSL backend, and use standard/primitive structs for frontend API. The frontend should not include any M\*Lib headers.
 
 # Documentation
 
@@ -115,15 +115,14 @@ For reference, Doxygen comment blocks can contain complex markup based on a larg
 
 When M*LIB macros are used to declare type-safe containers, the Doxygen inspection of the macro-expanded code should be inhibited but there should also be a explicit Doxygen block to provide explanation of the purpose of the struct and a reference to the type of its contents.
 
-An example of this is below (corresponding to @ref BSL_PolicyActionIList_t).
+An example of this is below (corresponding to @ref BSL_SecCtxDict_t).
 
 @verbatim
-/** @struct BSL_PolocuActionIList
- * An [M-I-LIST](https://github.com/P-p-H-d/mlib/blob/master/README.md#m-i-list)
- * of ::BSL_PolicyAction_t items.
+/** @struct BSL_SecCtxDict_t
+ * Stable dict of security context descriptors (key: context id | value: descriptor struct)
  */
 /// @cond Doxygen_Suppress
-M_ILIST_DEF(BSL_PolicyActionList, BSL_PolicyAction_t)
+DICT_DEF2(BSL_SecCtxDict, uint64_t, M_BASIC_OPLIST, BSL_SecCtxDesc_t, M_POD_OPLIST)
 /// @endcond
 @endverbatim
 
@@ -188,7 +187,7 @@ Functions that can fail should have `int` return type and use the following comm
 **Zero**: Means success (unless clearly indicated otherwise in exceptional use-cases)
 **Positive**: Implies success, with some supplementary data. For example, a `_CreateBlock()` function, upon success, would return a positive integer containing the ID of the block just created.
 
-NOTE!! This pattern is being adapted. A negative value indicates error, zero indicates succes.
+NOTE!! This pattern is being adapted. A negative value indicates error, zero indicates success.
 There may be times when there may be meaningful context associated with a positive value (e.g., number of bytes written).
 
 # Structs and Functions
@@ -233,14 +232,14 @@ The precondition checks (on function parameters or on any other state generally)
 - [CHKVOID(cond)](@ref CHKVOID) when the function has an `void` return type
 - [CHKFALSE(cond)](@ref CHKFALSE) when the function has an `bool` return type
 
-# Enums
+# Enumerations
 
-Enums with explicit values must be justified with citations, for example the declarations of @ref BSL_BundleBlockTypeCode_e.
+Enumerations with explicit values must be justified with citations, for example the declarations of @ref BSL_BundleBlockTypeCode_e.
 Otherwise, they should not be given values.
 
-Whenever possible, enums starting with zero should be avoided (since many variables default to zero, we want to avoid the case of matching an enum variant with an uninitialized, zeroed-out, value)
+Whenever possible, enum values starting with zero should be avoided (since many variables default to zero, we want to avoid the case of matching an enum variant with an uninitialized, zeroed-out, value)
 
-Enums should be `typedef`-ed with a `_e` suffix.
+Enumerations should be `typedef`-ed with a `_e` suffix.
 Enum values should be full `SCREAMING_CASE` matching the name of the struct.
 @verbatim
 typedef enum {

docs/api/Doxyfile.in

@@ -452,7 +452,7 @@ INLINE_SIMPLE_STRUCTS  = NO
 # types are typedef'ed and only the typedef is referenced, never the tag name.
 # The default value is: NO.
 
-TYPEDEF_HIDES_STRUCT   = NO
+TYPEDEF_HIDES_STRUCT   = YES
 
 # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
 # cache is used to resolve symbols given their name and scope. Since this can be
@@ -871,12 +871,10 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-#INPUT                  = . \
-#                         "@CMAKE_SOURCE_DIR@/src" \
-#                         "@CMAKE_BINARY_DIR@/src" \
-#                         "@CMAKE_SOURCE_DIR@/test"
 INPUT                  = . \
-                         "@CMAKE_SOURCE_DIR@/src" 
+                         "@CMAKE_SOURCE_DIR@/src" \
+                         "@CMAKE_BINARY_DIR@/src" \
+                         "@CMAKE_SOURCE_DIR@/test"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2595,7 +2593,7 @@ DIAFILE_DIRS           =
 # generate a warning when it encounters a \startuml command in this case and
 # will not generate output for the diagram.
 
-PLANTUML_JAR_PATH      =
+PLANTUML_JAR_PATH      = @PLANTUML_JAR@
 
 # When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a
 # configuration file for plantuml.

docs/api/InterfaceSpec.md

@@ -20,7 +20,7 @@ Institute of Technology, sponsored by the United States Government under
 the prime contract 80NM0018D0004 between the Caltech and NASA under
 subcontract 1700763.
 -->
-This document functions as the AMMOS MiMTAR required interface specificaiton.
+This document functions as the AMMOS MiMTAR required interface specification.
 
 Bundle Protocol Security Library (BPSec Lib) Software Interface Specification
 =============================================================================
@@ -114,7 +114,7 @@ The BSL is regression-tested and targeted primarily toward a RHEL-9 platform on
 
 The BSL defines a software interface written in C to maximize suitability for host applications regardless of their choice of programming language.
 
-The BSL is expected to operate on a host with FIPS 140-mode enabled and SE Linux enforcing. Developers must test in this environment otherwise undefined behaviour may occur.
+The BSL is expected to operate on a host with FIPS 140-mode enabled and SE Linux enforcing. Developers must test in this environment otherwise undefined behavior may occur.
 
 
 ## 2.2: Interface Medium and Characteristics
@@ -180,15 +180,15 @@ An example Policy Provider is included in the repository, as well as an implemen
 Refer to the doxygen-generated documentation in the repository for the relevant BSL initialization functions, that provision the library with the appropriate policy provider and security context.
 
 
-## 3.5:  BSL Bundle Lifecycles and Workflos
+## 3.5:  BSL Bundle Lifecycles and Workflows
 
 At each of the four points of contact between the BPA and BSL, the BPA invokes the BSL, which goes on to query the security policy provider, and returns an ordered list of security operations to be performed on the bundle according to local security policy.
 
 The BPA then iterates through this list calling the relevant BSL functions to perform the given security operation. These operations are of two types. The first simply verifies a given security result indicating whether it is successful or a failure reason code, and does not manipulate the Bundle in any way. The second type, indicated by “finalize” in the relevant API function names, either apply a new security Block to the bundle, modify a Block in the bundle, or strip a security block from a Bundle (following its successful verification).
 
 ## 3.6: Software Dependencies
 
-The BSL strives to avoid excessive reliance on third-party libraries and a long software supply chain. A few third-party libraries are required, however, to: provide dynamic data structures for this C codebase; provide a unit-test driver; provide a codec for CBOR-encoded Bundle blocks; and provide implementations of cryptographic algorithms. At the time of the Critical Design Review, these third-party open-source libraries respectively are MLib, Unity, QCBOR, and OpenSSL. 
+The BSL strives to avoid excessive reliance on third-party libraries and a long software supply chain. A few third-party libraries are required, however, to: provide dynamic data structures for this C codebase; provide a unit-test driver; provide a CODEC for CBOR-encoded Bundle blocks; and provide implementations of cryptographic algorithms. At the time of the Critical Design Review, these third-party open-source libraries respectively are MLib, Unity, QCBOR, and OpenSSL. 
 
 Note that specific library versions are detailed in Release Description Documents (RDD), which is produced with each release of BSL.
 

docs/api/UserGuide.md

@@ -59,7 +59,7 @@ digraph example {
 }
 @enddot
 
-The BSL comes with a @ref frontend and a @ref backend_dyn implementation which uses heap-allocated, dynamially-sized data structures and run-time registration capabilities.
+The BSL comes with a @ref frontend and a @ref backend_dyn implementation which uses heap-allocated, dynamically-sized data structures and run-time registration capabilities.
 For a more constrained (_e.g._, flight software) environment an alternative backend could be implemented with fixed-size data containers and constant-time registry lookup algorithms.
 
 Along with these libraries are also two integration extensions: an _Example Policy_ module and a _Default Security Contexts_ module.