From 0dae7a002ba5262b3babc674662d16b3370c2504 Mon Sep 17 00:00:00 2001 From: Leon Lynch Date: Mon, 8 Apr 2024 20:41:17 +0200 Subject: [PATCH] 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 | 8 ++++++++ src/CMakeLists.txt | 1 + src/emv_fields.h | 10 +++++----- src/emv_strings.h | 2 +- src/iso7816_compact_tlv.h | 2 +- src/iso8825_ber.h | 2 +- src/pcsc.h | 12 +++++++++--- tools/print_helpers.c | 6 +++--- 8 files changed, 29 insertions(+), 14 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 146433c..28ee3a0 100644 --- a/CMakeLists.txt +++ b/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) diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 1f91f6e..32751cc 100644 --- a/src/CMakeLists.txt +++ b/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 diff --git a/src/emv_fields.h b/src/emv_fields.h index 57602c7..205389f 100644 --- a/src/emv_fields.h +++ b/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 diff --git a/src/emv_strings.h b/src/emv_strings.h index 4e3e7b0..54b359a 100644 --- a/src/emv_strings.h +++ b/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 diff --git a/src/iso7816_compact_tlv.h b/src/iso7816_compact_tlv.h index 0455a73..0380da8 100644 --- a/src/iso7816_compact_tlv.h +++ b/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 diff --git a/src/iso8825_ber.h b/src/iso8825_ber.h index b413fdc..5362428 100644 --- a/src/iso8825_ber.h +++ b/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 diff --git a/src/pcsc.h b/src/pcsc.h index 45cef9d..15a8d00 100644 --- a/src/pcsc.h +++ b/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); diff --git a/tools/print_helpers.c b/tools/print_helpers.c index e42e658..f5f43eb 100644 --- a/tools/print_helpers.c +++ b/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; }