Improve documents

Author: terrillmoore

Doxyfile

@@ -434,7 +434,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
@@ -485,7 +485,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,
@@ -610,7 +610,7 @@ SORT_MEMBER_DOCS       = YES
 # this will also influence the order of the classes in the class list.
 # The default value is: NO.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
 # (brief and detailed) documentation of class members so that constructors and
@@ -1699,7 +1699,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2161,7 +2161,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             =        _DOXYGEN_
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

src/se/drivers/default/lmic_se_default.c

@@ -97,8 +97,8 @@ static int aes_verifyMic (const u1_t *key, u4_t devaddr, u4_t seqno, int dndir,
 \par "Implementation Details" 
     This implementation requires that \p iKey be \ref LMIC_SecureElement_KeySelector_Unicast.
 
-\retval     \ref LMIC_SecureElement_Error_OK means that the MIC was valid.
-\retval     \ref LMIC_SecureElement_Error_InvalidMIC means that the MIC was not valid.
+\retval     LMIC_SecureElement_Error_OK means that the MIC was valid.
+\retval     LMIC_SecureElement_Error_InvalidMIC means that the MIC was not valid.
 
 */
 
@@ -152,8 +152,8 @@ static void aes_cipher (xref2cu1_t key, u4_t devaddr, u4_t seqno, int dndir, xre
     the port number. This is used to select either \c AppSKey or \c NwkSKey to
     encode and MIC the message.
 
-\retval     \ref LMIC_SecureElement_Error_OK means that the MIC was valid.
-\retval     \ref LMIC_SecureElement_Error_InvalidMIC means that the MIC was not valid.
+\retval     LMIC_SecureElement_Error_OK means that the MIC was valid.
+\retval     LMIC_SecureElement_Error_InvalidMIC means that the MIC was not valid.
 
 */
 
@@ -380,6 +380,7 @@ LMIC_SecureElement_Default_decodeJoinAccept(
 
 \post
     \ref AESKey is set to the contents of \p pKey.
+
 */
 
 LMIC_SecureElement_Error_t

src/se/i/lmic_secure_element_api.h

@@ -30,12 +30,39 @@ Copyright & License:
 |   static binding.
 \****************************************************************************/
 
+#if defined(_DOXYGEN_)
+/// \brief Select the secure-element driver
+///
+/// \details
+///     This macro must be set to the name used by the secure element driver for
+///     its API functions. The default is `Default`.
+///
+/// \hideinitializer
+///
+# define LMIC_CFG_SecureElement_DRIVER   Default
+
+/// \brief Select linkage style
+///
+/// \details
+///     If this macro is defined and non-zero, the secure element will
+///     be integrated with the LMIC at compile time. If defined and zero,
+///     the secure element driver will be accessed via external functions,
+///     allowing the integration to be deferred to link time or run time.
+///
+/// \note
+///     At present, only compile-time integration is implemented.
+///
+/// \hideinitializer
+////
+# define LMIC_ENABLE_SecureElement_STATIC    1
+#endif
+
 #if ! defined(LMIC_CFG_SecureElement_DRIVER)
 # define LMIC_CFG_SecureElement_DRIVER   Default
 #endif
 
 #if ! defined(LMIC_ENABLE_SecureElement_STATIC)
-#define LMIC_ENABLE_SecureElement_STATIC    1
+# define LMIC_ENABLE_SecureElement_STATIC    1
 #endif
 
 /****************************************************************************\
@@ -71,12 +98,65 @@ LMIC_SecureElement_aes128Encrypt_t LMIC_SecureElement_aes128Encrypt;
 /*
 || Use static linkage for the APIs.
 */
+
+/// \brief Generate a method function name without argument expansion
+/// \param a_driver The name of the driver (will be macro-expanded)
+/// \param a_fn     The function-name fragment (will be macro-expanded)
+///
+/// \details
+///     This macro is like \ref LMIC_SecureElement_METHOD() except that
+///     macros in the arguments are not expanded prior performing string substitution.
+///
+///     For example, writing:
+///
+///     \code
+///     #define LMIC_CFG_SecureElement_DRIVER Foo
+///     LMIC_SecureElement_METHOD(LMIC_CFG_SecureElement_DRIVER, initialize)();
+///     \endcode
+///
+///     is the same as writing:
+///
+///     \code
+///     LMIC_SecureElement_LMIC_CFG_SecureElement_DRIVER_initialize();
+///     \endcode
+///
+/// \see LMIC_SecureElement_METHOD()
+/// \hideinitializer
+///
 #define LMIC_SecureElement_METHOD_(a_driver, a_fn)  \
     (LMIC_SecureElement_##a_driver##_##a_fn)
+
+/// \brief Generate a method function name
+/// \param a_driver The name of the driver (will be macro-expanded)
+/// \param a_fn     The function-name fragment (will be macro-expanded)
+///
+/// \details
+///     This macro returns a standard method function name. Standard method
+///     function names begin with `LMIC_SecureElement_`, followed by _a_driver_,
+///     followed by an underscore `_`, and ending with _a_fn_.
+///     For example, writing:
+///
+///     \code
+///     #define LMIC_CFG_SecureElement_DRIVER Foo
+///     LMIC_SecureElement_METHOD(LMIC_CFG_SecureElement_DRIVER, initialize)();
+///     \endcode
+///
+///     is the same as writing:
+///
+///     \code
+///     LMIC_SecureElement_Foo_initialize();
+///     \endcode
+///
+///     This macro is primarily intended for internal use.
+///
+/// \hideinitializer
+///
 #define LMIC_SecureElement_METHOD(a_driver, a_fn)  \
     LMIC_SecureElement_METHOD_(a_driver, a_fn)
 
+/// \cond FALSE
 LMIC_SecureElement_DECLARE_DRIVER_FNS(Default);
+/// \endcond
 
 /// \copydoc LMIC_SecureElement_initialize_t
 static inline
@@ -200,7 +280,7 @@ LMIC_SecureElement_Error_t LMIC_ABI_STD
 LMIC_SecureElement_decodeMessage(
     const uint8_t *pPhyPayload, uint8_t nPhyPayload,
     uint32_t devAddr, uint32_t FCntDown,
-    LMIC_SecureElement_KeySelector_t iKey, 
+    LMIC_SecureElement_KeySelector_t iKey,
     uint8_t *pClearTextBuffer
 ) {
     return LMIC_SecureElement_METHOD(LMIC_CFG_SecureElement_DRIVER, decodeMessage)(