Fixing typos in doxygen markup (#189)

* Fixing typos in doxygen cross-references

* Update mock bpa help message

Author: BrianSipos

docs/api/04-examples-and-mocks.md

@@ -29,7 +29,7 @@ The BSL proper is associated with the @ref frontend and @ref backend_dyn groups.
 The unit tests of the BSL use, where necessary, very minimal implementations of a PP to set up preconditons for test cases.
 
 The Mock BPA uses a PP implementation tailored to meet the needs of the BSL acceptance tests.
-This PP uses a set of bit fields within an integer program argument to control policy options; the fields are documented on ::bsl_mock_policy_configuration_t.
+This PP uses a set of bit fields within an integer program argument to control policy options; the fields are documented on ::BSLP_BitstringPolicyConfiguration_t.
 It also allows multiple integer policy values to be configured in a single running Mock BPA.
 This PP is registered and used by the @ref mock-bpa for many BSL testing cases.
 
@@ -65,7 +65,7 @@ The policies used by the Mock BPA example policy providers can be provided with
 
 ### Policy Bit Fields
 
-This policy provider initializes its policy using a set of bit fields within an integer program argument to control policy options; the fields are documented on ::bsl_mock_policy_configuration_t. 
+This policy provider initializes its policy using a set of bit fields within an integer program argument to control policy options; the fields are documented on ::BSLP_BitstringPolicyConfiguration_t. 
 The bit fields should be comma-separated, and passed to the Mock BPA with the `-p` command line option (see [Command Line Options](#command-line-options)).
 
 ### ION-Like JSON-Encoded Policy

docs/api/Doxyfile.in

@@ -924,10 +924,10 @@ BSL_ReasonCode_t BSL_SecOper_GetReasonCode(const BSL_SecOper_t *self);
  */
 void BSL_SecOper_SetReasonCode(BSL_SecOper_t *self, BSL_ReasonCode_t new_reason_code);
 
-/// Forward declaration of this struct
+// Forward declaration of this struct
 typedef struct BSL_AbsSecBlock_s BSL_AbsSecBlock_t;
 
-/// @brief Returns the size of the ::BSL_AbsSecBlock_t struct in bytes
+/// @brief Returns the size of the ::BSL_AbsSecBlock_s struct in bytes
 /// @return size of the struct
 size_t BSL_AbsSecBlock_Sizeof(void);
 

src/BPSecLib_Private.h

@@ -51,29 +51,32 @@ extern "C" {
 #define BSL_REQUIRE_CHECK
 #endif
 
-/// Forward declaration for BSL library context.
+// Forward declaration of this struct.
 typedef struct BSL_LibCtx_s BSL_LibCtx_t;
 
 /**
  * Return size of library context
  */
 size_t BSL_LibCtx_Sizeof(void);
 
-/// @brief Forward declaration of ::BSL_SecurityResponseSet_s, which contains information for BSL and the host BPA to
-/// process the Bundle.
+// Forward declaration of this struct.
+// This contains information for BSL and the host BPA to process the Bundle.
 typedef struct BSL_SecurityResponseSet_s BSL_SecurityResponseSet_t;
 
-/// @brief Forward declaration of ::BSL_SecurityActionSet_s, which contains actions for BSL to process the Bundle.
+// Forward declaration of this struct.
+// This contains actions for BSL to process the Bundle.
 typedef struct BSL_SecurityActionSet_s BSL_SecurityActionSet_t;
 
-/// @brief Forward declaration of ::BSL_SecurityAction_s, which contains security operations for BSL to process the
-/// Bundle.
+// Forward declaration of this struct.
+// This contains security operations for BSL to process the Bundle.
 typedef struct BSL_SecurityAction_s BSL_SecurityAction_t;
 
-/// @brief Forward-declaration for structure containing callbacks to a security context.
+// Forward declaration of this struct.
+// This contains callbacks to a security context.
 typedef struct BSL_SecCtxDesc_s BSL_SecCtxDesc_t;
 
-/// @brief Forward-declaration for structure containing callbacks to  provider.
+// Forward declaration of this struct.
+// This contains callbacks to a policy provider.
 typedef struct BSL_PolicyDesc_s BSL_PolicyDesc_t;
 
 /** @brief Indicates where in the lifecycle of the BPA the bundle is querying for security policy.
@@ -300,7 +303,7 @@ typedef struct
 
 /** Dynamic BPA descriptor.
  *
- * @caution All functions in this structure must be thread safe, as they
+ * @warning All functions in this structure must be thread safe, as they
  * can be called by any number of BSL instances across any threads.
  */
 typedef struct
@@ -432,7 +435,7 @@ typedef struct
 /** Set the BPA descriptor (callbacks) for this process.
  *
  * @warning This function is not thread safe and should be used before any
- * ::BSL_LibCtx_t is initialized or other BSL interfaces used.
+ * ::BSL_LibCtx_s is initialized or other BSL interfaces used.
  *
  * @param desc The descriptor to use for future BPA functions.
  * @return Zero if successful, negative on error.
@@ -449,7 +452,7 @@ void BSL_HostDescriptors_Get(BSL_HostDescriptors_t *desc);
 /** Reset the host descriptors to their default, unusable state.
  *
  * @warning This function is not thread safe and should be used after any
- * ::BSL_LibCtx_t is deinitialized.
+ * ::BSL_LibCtx_s is deinitialized.
  */
 void BSL_HostDescriptors_Clear(void);
 

src/BPSecLib_Public.h

@@ -78,13 +78,13 @@ struct BSL_SecParam_s
     m_bstring_t _bytes;
 };
 
-/// OPLIST for ::BSL_SecParam_t
+/// OPLIST for ::BSL_SecParam_s
 #define M_OPL_BSL_SecParam_t()                                                                                 \
     (INIT(API_2(BSL_SecParam_Init)), INIT_SET(API_6(BSL_SecParam_InitSet)), CLEAR(API_2(BSL_SecParam_Deinit)), \
      SET(API_6(BSL_SecParam_Set)))
 
 /** @struct BSLB_SecParamList_t
- * Defines a basic list of Security Parameters (::BSL_SecParam_t).
+ * Defines a basic list of Security Parameters (::BSL_SecParam_s).
  */
 // NOLINTBEGIN
 /// @cond Doxygen_Suppress

src/backend/SecParam.h

@@ -91,13 +91,13 @@ struct BSL_SecResult_s
     m_bstring_t _bytes;
 };
 
-/// OPLIST for ::BSL_SecParam_t
+/// OPLIST for ::BSL_SecParam_s
 #define M_OPL_BSL_SecResult_t()                                                                                   \
     (INIT(API_2(BSL_SecResult_Init)), INIT_SET(API_6(BSL_SecResult_InitSet)), CLEAR(API_2(BSL_SecResult_Deinit)), \
      SET(API_6(BSL_SecResult_Set)))
 
 /** @struct BSLB_SecResultList_t
- * Defines a basic list of Security Results (::BSL_SecResult_t).
+ * Defines a basic list of Security Results (::BSL_SecResult_s).
  */
 /// @cond Doxygen_Suppress
 // NOLINTBEGIN

src/backend/SecResult.h

@@ -23,13 +23,13 @@
 #include <BPSecLib_Private.h>
 #include "SecOperation.h"
 
-/// OPLIST for ::BSL_SecOper_t
+/// OPLIST for ::BSL_SecOper_s
 #define M_OPL_BSL_SecOper_t()                                                                          \
     (INIT(API_2(BSL_SecOper_Init)), INIT_SET(API_6(BSL_SecOper_InitSet)), SET(API_6(BSL_SecOper_Set)), \
      CLEAR(API_2(BSL_SecOper_Deinit)))
 
 /** @struct BSL_SecOperList_t
- * Defines a basic list of ::BSL_SecOper_t.
+ * Defines a basic list of ::BSL_SecOper_s.
  */
 /// @cond Doxygen_Suppress
 // NOLINTBEGIN

src/backend/SecurityAction.h

@@ -30,7 +30,7 @@
 #include "SecurityAction.h"
 
 /** @struct BSL_SecActionList_t
- * Defines a basic list of ::BSL_SecurityAction_t.
+ * Defines a basic list of ::BSL_SecurityAction_s.
  */
 /// @cond Doxygen_Suppress
 // NOLINTBEGIN

src/backend/SecurityActionSet.h

@@ -31,7 +31,7 @@
 #include <m-array.h>
 
 /** @struct BSL_SecResultSet_ResultCodes
- * Defines a basic list of ::int64_t for result values.
+ * Defines a basic list of @c int64_t for result values.
  */
 /** @struct BSL_SecResultSet_ErrorActionCodes_t
  * Defines a basic list of ::BSL_PolicyAction_e.

src/backend/SecurityResultSet.h

@@ -98,15 +98,22 @@ static void sig_stop(int signum)
 static void show_usage(const char *argv0)
 {
     fprintf(stderr,
-            "Usage: %s -o <over-socket address:port> -a <application address:port>\n"
-            "          -u <under-socket address:port> -r <router address:port>\n"
-            "          -e <app-EID> -s <sec-src-EID>\n"
-            "          -p (optional - defaults to none) comma delimited hex list of <bsl_mock_policy_configuration_t>, "
-            "e.g. '0x000f,0x0021'\n"
-            "          -j (optional - defaults to none) path to JSON file containing policy configuration\n"
-            "          -k (optional - defaults to none) path to JSON file containing JWKs to register\n"
-            "          -c (optional - defaults to OpenSSL RAND) enable custom RNG generator for testing purposes\n",
-            argv0);
+            // options use the form of man-pages.7
+            "BSL Mock BPA v%s\n\n"
+            "Usage: %s [options]\n"
+            "Where the options are:\n"
+            "    {-o <address:port>} the over-socket UDP listen\n"
+            "    {-a <address:port>} the application UDP address\n"
+            "    {-u <address:port>} the under-socket UDP listen\n"
+            "    {-r <address:port>} the neighbor UDP address\n"
+            "    {-e <app-EID>} the overlayer application BPv7 EID\n"
+            "    {-s <sec-src-EID>} the security source BPv7 EID\n"
+            "    [-p <hex-list>] comma delimited hex list of <BSLP_BitstringPolicyConfiguration_t>, "
+            "e.g. '0x000f,0x0021' (default: none)\n"
+            "    [-j <file-path>] path to JSON file containing policy configuration (default: none)\n"
+            "    [-k <file-path>] path to JSON file containing JWKs to register (default: none)\n"
+            "    [-c] enable custom RNG generator for testing purposes (default: use OpenSSL RAND)\n",
+            BSL_VERSION, argv0);
 }
 
 int main(int argc, char **argv)