Update platform.h
Minor documentation improvements:
*Standardized file brief description.
*Reordered tags within documentation blocks so that params and returns are last in block.
*Some minor rephrasing.
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index ed10775..65ae85c 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -1,7 +1,8 @@
/**
* \file platform.h
*
- * \brief The Mbed TLS platform abstraction layer.
+ * \brief This file contains the definitions and functions of the
+ * Mbed TLS platform abstraction layer.
*/
/*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -102,7 +103,7 @@
/* \} name SECTION: Module settings */
/*
- * The function pointers for calloc and free
+ * The function pointers for calloc and free.
*/
#if defined(MBEDTLS_PLATFORM_MEMORY)
#if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
@@ -116,7 +117,8 @@
extern void (*mbedtls_free)( void *ptr );
/**
- * \brief This function allows configuring custom memory-management functions.
+ * \brief This function allows configuring custom
+ * memory-management functions.
*
* \param calloc_func The \c calloc function implementation.
* \param free_func The \c free function implementation.
@@ -140,7 +142,8 @@
extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
/**
- * \brief This function allows configuring a custom \p fprintf function pointer.
+ * \brief This function allows configuring a custom
+ * \p fprintf function pointer.
*
* \param fprintf_func The \c fprintf function implementation.
*
@@ -163,8 +166,8 @@
extern int (*mbedtls_printf)( const char *format, ... );
/**
- * \brief This function allows configuring a custom \c printf function
- * pointer.
+ * \brief This function allows configuring a custom \c printf
+ * function pointer.
*
* \param printf_func The \c printf function implementation.
*
@@ -197,12 +200,12 @@
extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
/**
- * \brief This function allows configuring a custom \c snprintf function
- * pointer.
+ * \brief This function allows configuring a custom
+ * \c snprintf function pointer.
*
* \param snprintf_func The \c snprintf function implementation.
*
- * \return \c 0 on success.
+ * \return \c 0 on success.
*/
int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
const char * format, ... ) );
@@ -221,12 +224,12 @@
extern void (*mbedtls_exit)( int status );
/**
- * \brief This function allows configuring a custom \c exit function
- * pointer.
+ * \brief This function allows configuring a custom
+ * \c exit function pointer.
*
* \param exit_func The \c exit function implementation.
*
- * \return \c 0 on success.
+ * \return \c 0 on success.
*/
int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
#else
@@ -302,7 +305,7 @@
* setup or teardown operations.
*/
typedef struct {
- char dummy; /**< Placeholder member, as empty structs are not portable. */
+ char dummy; /**< A placeholder member, as empty structs are not portable. */
}
mbedtls_platform_context;
@@ -311,33 +314,33 @@
#endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
/**
- * \brief This function performs any platform initialization operations.
+ * \brief This function performs any platform-specific initialization operations.
+ *
+ * \note This function should be called before any other library functions.
+ *
+ * Its implementation is platform-specific, and unless
+ * platform-specific code is provided, it does nothing.
+ *
+ * \note The usage and necessity of this function is dependent on the platform.
*
* \param ctx The Mbed TLS context.
*
* \return \c 0 on success.
- *
- * \note This function is intended to allow platform-specific initialization,
- * and should be called before any other library functions. Its
- * implementation is platform-specific, and unless
- * platform-specific code is provided, it does nothing.
- *
- * Its use and whether it is necessary to call it is dependent on the
- * platform.
*/
int mbedtls_platform_setup( mbedtls_platform_context *ctx );
/**
* \brief This function performs any platform teardown operations.
*
- * \param ctx The Mbed TLS context.
- *
* \note This function should be called after every other Mbed TLS module
* has been correctly freed using the appropriate free function.
+ *
* Its implementation is platform-specific, and unless
* platform-specific code is provided, it does nothing.
*
- * Its use and whether it is necessary to call it is dependent on the
- * platform.
+ * \note The usage and necessity of this function is dependent on the platform.
+ *
+ * \param ctx The Mbed TLS context.
+ *
*/
void mbedtls_platform_teardown( mbedtls_platform_context *ctx );