Misc Doxygen and error string improvements

* Allow static functions and inline functions in Doxygen output
* Use Doxygen preprocessor to ignore GCC __attribute__ which would
  otherwise be interpreted as a function
* Add iso7816_apdu.h to iso7816 library header list
* Fix various Doxygen typos
* Fix various error string typos

CMakeLists.txt

@@ -204,6 +204,14 @@ find_package(Doxygen) # Optional for generating doxygen files
 if(Doxygen_FOUND)
 	# Use doxygen to generate HTML
 	set(DOXYGEN_GENERATE_HTML YES)
+	# Allow static functions and variables
+	set(DOXYGEN_EXTRACT_STATIC YES)
+	# Allow inline functions
+	set(DOXYGEN_INLINE_SOURCES YES)
+	# Ignore uses of GCC __attribute__
+	set(DOXYGEN_MACRO_EXPANSION YES)
+	set(DOXYGEN_EXPAND_ONLY_PREDEF YES)
+	set(DOXYGEN_PREDEFINED "__attribute__(x)=")
 
 	# Generate docs for public headers
 	if(BUILD_DOCS)

src/CMakeLists.txt

@@ -111,6 +111,7 @@ add_library(iso7816
 )
 set(iso7816_HEADERS # PUBLIC_HEADER property requires a list instead of individual entries
 	iso7816.h
+	iso7816_apdu.h
 	iso7816_compact_tlv.h
 	iso7816_strings.h
 	PARENT_SCOPE # Doxygen generator requires a list of headers

src/emv_fields.h

@@ -39,8 +39,8 @@ __BEGIN_DECLS
 
 // Application Selection Indicator
 // See EMV 4.4 Book 1, 12.3.1
-#define EMV_ASI_EXACT_MATCH                                     (0x00)
-#define EMV_ASI_PARTIAL_MATCH                                   (0x01)
+#define EMV_ASI_EXACT_MATCH                                     (0x00) ///< Application Selection Indicator: Exact match required
+#define EMV_ASI_PARTIAL_MATCH                                   (0x01) ///< Application Selection Indicator: Partial match allowed
 
 // Transaction Type (field 9C)
 // See ISO 8583:1987, 4.3.8
@@ -495,7 +495,7 @@ enum emv_iad_format_t {
 
 // Card Verification Results (CVR) byte 1 for Visa Smart Debit/Credit (VSDC) IAD Format 2/4 applications
 // NOTE: From unverified internet sources
-#define EMV_IAD_VSDC_CVR_BYTE1_CVM_ENTITY_MASK                  (0xF0) ///< Card Verification Results (CVR) mask CVM Verifying Entity
+#define EMV_IAD_VSDC_CVR_BYTE1_CVM_ENTITY_MASK                  (0xF0) ///< Card Verification Results (CVR) mask for CVM Verifying Entity
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_ENTITY_NONE                  (0x00) ///< Card Verification Results (CVR): No CDCVM
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_ENTITY_VMPA                  (0x10) ///< Card Verification Results (CVR): Visa Mobile Payment Application (VMPA)
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_ENTITY_MG                    (0x20) ///< Card Verification Results (CVR): MG
@@ -505,7 +505,7 @@ enum emv_iad_format_t {
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_ENTITY_TERMINAL              (0x60) ///< Card Verification Results (CVR): Terminal
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_ENTITY_CLOUD                 (0x70) ///< Card Verification Results (CVR): Verified in the cloud
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_ENTITY_MOBILE_DEVICE_OS      (0x80) ///< Card Verification Results (CVR): Verified by the mobile device OS
-#define EMV_IAD_VSDC_CVR_BYTE1_CVM_TYPE_MASK                    (0x0F) ///< Card Verification Results (CVR) mask CVM Verified Type
+#define EMV_IAD_VSDC_CVR_BYTE1_CVM_TYPE_MASK                    (0x0F) ///< Card Verification Results (CVR) mask for CVM Verified Type
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_TYPE_NONE                    (0x00) ///< Card Verification Results (CVR): No CDCVM
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_TYPE_PASSCODE                (0x01) ///< Card Verification Results (CVR): Passcode
 #define EMV_IAD_VSDC_CVR_BYTE1_CVM_TYPE_BIOMETRIC_FINGER        (0x02) ///< Card Verification Results (CVR): Finger biometric
@@ -897,7 +897,7 @@ struct emv_cv_rule_t {
 };
 
 /**
- * Initialize Cardholder Verification Method (CVM) List amounts and iterator
+ * Initialise Cardholder Verification Method (CVM) List amounts and iterator
  * @param cvmlist Cardholder Verification Method (CVM) List field
  * @param cvmlist_len Length of Cardholder Verification Method (CVM) List field
  * @param amounts Cardholder Verification Method (CVM) List amounts output

src/emv_strings.h

@@ -119,7 +119,7 @@ struct emv_tlv_info_t {
 };
 
 /**
- * Initialize EMV strings. This will load ISO 3166, ISO 4217,
+ * Initialise EMV strings. This will load ISO 3166, ISO 4217,
  * and ISO 639 strings from the iso-codes package.
  *
  * @param isocodes_path Override directory path where iso-codes JSON files can

src/iso7816_compact_tlv.h

@@ -61,7 +61,7 @@ struct iso7816_compact_tlv_t {
 int iso7816_compact_tlv_decode(const void* buf, size_t len, struct iso7816_compact_tlv_t* tlv);
 
 /**
- * Initialize COMPACT-TLV iterator
+ * Initialise COMPACT-TLV iterator
  * @param buf COMPACT-TLV buffer
  * @param len Length of COMPACT-TLV buffer in bytes
  * @param itr Iterator output

src/iso8825_ber.h

@@ -166,7 +166,7 @@ static inline bool iso8825_ber_is_constructed(const struct iso8825_tlv_t* tlv) {
 bool iso8825_ber_is_string(const struct iso8825_tlv_t* tlv);
 
 /**
- * Initialize BER iterator
+ * Initialise BER iterator
  * @param ptr BER encoded data
  * @param len Length of BER encoded data in bytes
  * @param itr BER iterator output

src/pcsc.h

@@ -32,7 +32,12 @@ __BEGIN_DECLS
 typedef void* pcsc_ctx_t; ///< PC/SC context pointer type
 typedef void* pcsc_reader_ctx_t; ///< PC/SC reader context pointer type
 
-// NOTE: these are derived from PCSCLite's SCARD_STATE_* defines
+/**
+ * @name PC/SC reader states
+ * @remark These are derived from PCSCLite's SCARD_STATE_* defines
+ * @anchor pcsc-reader-states
+ */
+/// @{
 #define PCSC_STATE_CHANGED      (0x0002) ///< State has changed
 #define PCSC_STATE_UNAVAILABLE  (0x0008) ///< Status unavailable
 #define PCSC_STATE_EMPTY        (0x0010) ///< Card removed
@@ -42,6 +47,7 @@ typedef void* pcsc_reader_ctx_t; ///< PC/SC reader context pointer type
 #define PCSC_STATE_INUSE        (0x0100) ///< Shared Mode
 #define PCSC_STATE_MUTE         (0x0200) ///< Unresponsive card
 #define PCSC_STATE_UNPOWERED    (0x0400) ///< Unpowered card
+/// @}
 
 #define PCSC_TIMEOUT_INFINITE   (0xFFFFFFFF) ///< Infinite timeout
 #define PCSC_READER_ANY         (0xFFFFFFFF) ///< Use any reader
@@ -56,7 +62,7 @@ enum pcsc_card_type_t {
 };
 
 /**
- * Initialize PC/SC context
+ * Initialise PC/SC context
  * @param ctx PC/SC context pointer
  * @return Zero for success. Less than zero for error.
  */
@@ -93,7 +99,7 @@ const char* pcsc_reader_get_name(pcsc_reader_ctx_t reader_ctx);
 /**
  * Retrieve PC/SC reader state
  * @param reader_ctx PC/SC reader context
- * @param state PC/SC reader state output. See PCSC_STATE_* bits.
+ * @param state PC/SC reader state output. See @ref pcsc-reader-states "PC/SC reader states"
  * @return Zero for success. Less than zero for error.
  */
 int pcsc_reader_get_state(pcsc_reader_ctx_t reader_ctx, unsigned int* state);

tools/print_helpers.c

@@ -335,7 +335,7 @@ void print_ber_buf(const void* ptr, size_t len, const char* prefix, unsigned int
 
 	r = iso8825_ber_itr_init(ptr, len, &itr);
 	if (r) {
-		printf("Failed to initialize BER iterator\n");
+		printf("Failed to initialise BER iterator\n");
 		return;
 	}
 
@@ -455,7 +455,7 @@ void print_emv_buf(const void* ptr, size_t len, const char* prefix, unsigned int
 
 	r = iso8825_ber_itr_init(ptr, len, &itr);
 	if (r) {
-		printf("Failed to initialize BER iterator\n");
+		printf("Failed to initialise BER iterator\n");
 		return;
 	}
 
@@ -493,7 +493,7 @@ void print_emv_dol(const void* ptr, size_t len, const char* prefix, unsigned int
 
 	r = emv_dol_itr_init(ptr, len, &itr);
 	if (r) {
-		printf("Failed to initialize DOL iterator\n");
+		printf("Failed to initialise DOL iterator\n");
 		return;
 	}