From f05e498c732fa464a91e0b07cfc0e70bf348e0f4 Mon Sep 17 00:00:00 2001 From: Deepika Bhavnani Date: Fri, 2 Jun 2017 13:18:40 -0500 Subject: [PATCH] Resolving doxygen warnings --- platform/FileHandle.h | 28 +++++++++++++++++----------- platform/mbed_error.h | 8 +++++++- platform/mbed_interface.h | 14 +++++++++++++- platform/mbed_mem_trace.h | 12 ++++++------ 4 files changed, 43 insertions(+), 19 deletions(-) diff --git a/platform/FileHandle.h b/platform/FileHandle.h index 9db41d6c87..187f7c18ee 100644 --- a/platform/FileHandle.h +++ b/platform/FileHandle.h @@ -170,7 +170,10 @@ public: * Definition depends upon the subclass implementing FileHandle. * The default is blocking. * - * @param blocking true for blocking mode, false for non-blocking mode. + * @param blocking true for blocking mode, false for non-blocking mode. + * + * @return 0 on success + * @return Negative error code on failure */ virtual int set_blocking(bool blocking) { @@ -183,10 +186,9 @@ public: * Call is non-blocking - returns instantaneous state of events. * Whenever an event occurs, the derived class should call the sigio() callback). * - * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc. + * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc. * - * @returns - * bitmask of poll events that have occurred. + * @returns bitmask of poll events that have occurred. */ virtual short poll(short events) const { @@ -194,20 +196,22 @@ public: return POLLIN | POLLOUT; } - /** Returns true if the FileHandle is writable. - * Definition depends upon the subclass implementing FileHandle. + /** Definition depends upon the subclass implementing FileHandle. * For example, if the FileHandle is of type Stream, writable() could return * true when there is ample buffer space available for write() calls. + * + * @returns true if the FileHandle is writable. */ bool writable() const { return poll(POLLOUT) & POLLOUT; } - /** Returns true if the FileHandle is readable. - * Definition depends upon the subclass implementing FileHandle. + /** Definition depends upon the subclass implementing FileHandle. * For example, if the FileHandle is of type Stream, readable() could return * true when there is something available to read. + * + * @returns true when there is something available to read. */ bool readable() const { @@ -239,11 +243,13 @@ public: /** Not a member function * This call is equivalent to posix fdopen(). - * Returns a pointer to std::FILE. * It associates a Stream to an already opened file descriptor (FileHandle) * - * @param fh a pointer to an opened file descriptor - * @param mode operation upon the file descriptor, e.g., 'wb+'*/ + * @param fh a pointer to an opened file descriptor + * @param mode operation upon the file descriptor, e.g., 'wb+' + * + * @returns a pointer to std::FILE +*/ std::FILE *fdopen(FileHandle *fh, const char *mode); diff --git a/platform/mbed_error.h b/platform/mbed_error.h index 15fd5e8064..1da55135b9 100644 --- a/platform/mbed_error.h +++ b/platform/mbed_error.h @@ -19,7 +19,12 @@ #ifndef MBED_ERROR_H #define MBED_ERROR_H + + /** To generate a fatal compile-time error, you can use the pre-processor #error directive. + * + * @param format C string that contains data stream to be printed. + * Code snippets below show valid format. * * @code * #error "That shouldn't have happened!" @@ -54,12 +59,13 @@ * error("expected x to be less than 5, but got %d", x); * } * @endcode + * + * */ #ifdef __cplusplus extern "C" { #endif - void error(const char* format, ...); #ifdef __cplusplus diff --git a/platform/mbed_interface.h b/platform/mbed_interface.h index bb3e2a3489..538a6a7cbf 100644 --- a/platform/mbed_interface.h +++ b/platform/mbed_interface.h @@ -113,9 +113,17 @@ void mbed_mac_address(char *mac); void mbed_die(void); /** Print out an error message. This is typically called when - * hanlding a crash. + * handling a crash. * * @note Synchronization level: Interrupt safe + * + * @param format C string that contains data stream to be printed. + * Code snippets below show valid format. + * + * @code + * mbed_error_printf("Failed: %s, file: %s, line %d \n", expr, file, line); + * @endcode + * */ void mbed_error_printf(const char* format, ...); @@ -123,6 +131,10 @@ void mbed_error_printf(const char* format, ...); * but uses a va_list. * * @note Synchronization level: Interrupt safe + * + * @param format C string that contains data stream to be printed. + * @param arg Variable arguments list + * */ void mbed_error_vfprintf(const char * format, va_list arg); diff --git a/platform/mbed_mem_trace.h b/platform/mbed_mem_trace.h index 8efc05c7ca..0267255ba7 100644 --- a/platform/mbed_mem_trace.h +++ b/platform/mbed_mem_trace.h @@ -110,12 +110,12 @@ void mbed_mem_trace_free(void *ptr, void *caller); * easily parsable by an external tool. For each memory operation, the callback * outputs a line that begins with "#:<0xresult>;<0xcaller>-": * - * - 'op' identifies the memory operation ('m' for 'malloc', 'r' for 'realloc', - * 'c' for 'calloc' and 'f' for 'free'). - * - 'result' (base 16) is the result of the memor operation. This is always NULL - * for 'free', since 'free' doesn't return anything. - * - 'caller' (base 16) is the caller of the memory operation. Note that the value - * of 'caller' might be unreliable. + * @param op identifies the memory operation ('m' for 'malloc', 'r' for 'realloc', + * 'c' for 'calloc' and 'f' for 'free'). + * @param res (base 16) is the result of the memor operation. This is always NULL + * for 'free', since 'free' doesn't return anything. + * @param caller (base 16) is the caller of the memory operation. Note that the value + * of 'caller' might be unreliable. * * The rest of the output depends on the operation being traced: *